@dorkodu/sage

The marvelous data exchange protocol for APIs

About The Project

Sage allows you to easily build & consume fully typesafe APIs, without a query language, or code generation.

Features

• ✅  Describe your data requirements as resources.
• 🔐  Static type safety & auto-completion on the client for queries.
• ❌  No query/schema definition language, code generation, run-time bloat, or build pipeline.
• 🍃  Lightweight – Sage has zero dependencies and a tiny client-side footprint.
• 🔗  Work easily with any data source, a remote API, local cache.
• 📨 Infinite resources with one request.
• 🔋  Reference library in Typescript.
• 🗽  Liberating developer experience.
• ⏳  Fast, thanks to simplicity :)

Quickstart

With NPM:

$ npm install @dorkodu/sage

With Yarn:

$ yarn add @dorkodu/sage

With PNPM:

$ pnpm add @dorkodu/sage

Import Sage:

import { sage } from "@dorkodu/sage";

Create a schema (in server):

interface Context {
  /* Constant context variables (eg. req, res, next from ExpressJS) */
  readonly req: Req;
  readonly res: Res;
  readonly next: Next;

  /* Non-constant context variables that are useful */
  userId?: number;
}

const auth = sage.resource(
  {} as Context,
  {} as { token: string },
  async (arg, ctx) => {
    // Validate "arg" (using zod, etc.), never trust the user input
    // Query database using "arg"
    return authStatus;
  }
)

const getUser = sage.resource(
  {} as Context,
  {} as { userId: number },
  async (arg, ctx) => {
    // Validate "arg" (using zod, etc.), never trust the user input
    // Query database using "arg"
    return user;
  }
)

export type Schema = typeof schema;
export const schema = sage.schema({} as Context, { auth, getUser });

Create a router using schema from server (in client):

export const router = sage.use<Schema>();

Send queries to server and get results:

const result = await router.get(
  {
    a: router.query("auth", { token: "..." }, { ctx: "ctx" }),
    b: router.query("getUser", { userId: 0 }, { ctx: "ctx", wait: "a" }),
  },
  async (queries) => {
    const result = await mockFetch(queries);
    return result;
  }
)

Result:

{
  "a": {
    "status": true,
    ...
  },
  "b": {
    "id": 0,
    "name": "Sage",
    ...
  }
}

Docs

Check out the full docs here: Docs

Examples

For more comprehensive use cases of Sage, you can check the examples:

• Blog Example

Real-World Uses

We are already using Sage on our applications. If you do, submit an issue and we will display you too.

• Dorkodu ID — (GitHub) - (Website)
• Dorkodu Forum — (GitHub) - (Website)

Authors

Berk Cambaz Project Lead & Developer Co-Founder & Chief Technologist @ Dorkodu

Doruk Eray Creator Founder & Chief @ Dorkodu

License

Distributed under the MIT License. See LICENSE for more information.