Fold API

How to define a fold's server: fold(), the schema, queries, mutations, actions, endpoints, and the ctx every handler receives.

All server code imports from @aozumi/fold/server. The default export of server/index.ts must be a fold({...}) call.

A complete server

import { action, boolean, endpoint, fold, json, mutation, query, string, table, text, userId } from "@aozumi/fold/server";
import { cleanBody } from "../shared/notes";

// shared/notes.ts: export function cleanBody(value: string): string { return value.trim().slice(0, 500); }

export default fold({
  name: "notes",

  auth: { requireSignIn: false },

  schema: {
    notes: table({
      body: string(),
      pinned: boolean().default(false),
      color: string().optional(),
      ownerId: userId()
    }).index("by_owner", ["ownerId"])
  },

  queries: {
    myNotes: query(async (ctx) => {
      const { userId } = ctx.auth.requireIdentity();
      return ctx.db.notes
        .withIndex("by_owner", (q) => q.eq("ownerId", userId))
        .order("desc")
        .take(100);
    })
  },

  mutations: {
    addNote: mutation(async (ctx, body: string) => {
      const { userId } = ctx.auth.requireIdentity();
      const clean = cleanBody(body);
      if (!clean) {
        throw new Error("Write something first.");
      }
      return ctx.db.notes.insert({ body: clean, ownerId: userId });
    }),
    removeNote: mutation(async (ctx, id: string) => {
      const { userId } = ctx.auth.requireIdentity();
      const note = await ctx.db.notes.get(id);
      if (!note || note.ownerId !== userId) {
        throw new Error("Note not found.");
      }
      await ctx.db.notes.delete(id);
    })
  },

  actions: {
    noteCount: action(async (ctx) => {
      const { userId } = ctx.auth.requireIdentity();
      const total = await ctx.db.notes.withIndex("by_owner", (q) => q.eq("ownerId", userId)).count();
      return { total };
    })
  },

  endpoints: {
    health: endpoint({ method: "GET", path: "/api/health" }, () => text("ok")),
    createNote: endpoint({ method: "POST", path: "/api/notes" }, async (ctx, req) => {
      const auth = ctx.auth.requireSignedIn();
      const payload = await req.json<{ body: string }>();
      const note = await ctx.db.notes.insert({ body: cleanBody(payload.body), ownerId: auth.userId });
      return json({ id: note.id }, { status: 201 });
    })
  }
});

fold(definition)

fold() accepts only these keys. Any other key throws Unknown fold() option.

Schema

schema: {
  lists: table({ title: string(), ownerId: userId() }).index("by_owner", ["ownerId"]),
  items: table({
    listId: id("lists"),
    text: string(),
    done: boolean().default(false),
    dueAt: number().optional()
  })
    .index("by_list", ["listId"])
    .index("by_list_due", ["listId", "dueAt"])
}

Field builders:

Modifiers, chainable on any field:

• .optional(): the field may be absent. Inserts may omit it or pass null.
• .default(value): used when an insert omits the field, and returned for older rows that lack it.

Rules:

• Table, field, and index names start with a letter and use only letters, digits, and _.
• id, createdAt, and updatedAt are reserved. Fold sets them on every row (createdAt and updatedAt are ISO strings).
• .index(name, fields) declares an index. Fields may include id, createdAt, and updatedAt. The name by_creation is reserved: every table already has it.
• Every index sorts by its fields, then createdAt, then id.

Only string, number, boolean, id, and userId exist. Store a timestamp as number() (epoch milliseconds). Store a list as rows in another table. See Database for queries.

Queries

query(async (ctx, args: { listId: string }) => {
  return ctx.db.items.withIndex("by_list", (q) => q.eq("listId", args.listId)).collect();
})

• Read-only database. Any write throws Query handlers have a read-only database capability.
• Live: a client subscribed with useQuery gets a new result whenever a table the query read changes.
• Give a query at most one argument and make it an object. The client sends it as JSON.
• The result must be JSON-compatible.

Mutations

mutation(async (ctx, listId: string, text: string) => {
  const { userId } = ctx.auth.requireIdentity();
  const list = await ctx.db.lists.get(listId);
  if (!list || list.ownerId !== userId) {
    throw new Error("List not found.");
  }
  return ctx.db.items.insert({ listId, text });
})

• Read and write. All writes in one call commit together or not at all. A thrown error rolls back every write.
• A mutation may take several positional arguments. Each must be JSON-compatible.
• Await or return every database call.
• Each call counts toward the daily mutation limit when hosted.

Actions

action(async (ctx, search: string) => {
  const matches = await ctx.db.items.withIndex("by_creation").order("desc").take(200);
  return matches.filter((item) => String(item.text).includes(search)).length;
})

• Read-only database, like a query, but not live: the client calls it once with useAction.
• Arguments up to 16 KiB, result up to 48 KiB, both JSON. Runs for at most 5 seconds.
• Each call counts toward the daily request and mutation limits when hosted.

Endpoints

endpoint({ method: "POST", path: "/api/items" }, async (ctx, req) => {
  const body = await req.json<{ listId: string; text: string }>();
  const item = await ctx.db.items.insert({ listId: body.listId, text: body.text });
  return json(item, { status: 201 });
})

endpoint(route, handler):

• route.method: an uppercase HTTP method, such as "GET" or "POST".
• route.path: an absolute path such as /api/items. No query string, fragment, or backslash. Paths are matched exactly. Reserved: /, /index.html, /client.js, /auth/..., /__fold/..., /__span/.... When hosted, /storage and /storage/... are taken by file storage, so do not use them.
• route.readOnly: defaults to true for GET and HEAD, false for other methods. A read-only endpoint gets a read-only ctx.db. A writable one runs in a transaction like a mutation and counts toward the daily mutation limit when hosted.

The request (EndpointRequest):

Body readers can be called more than once. The request body may be up to 2 MiB.

Return a response with a helper:

Endpoint callers authenticate with the same-origin guest cookie, or with a Google identity token in the X-Fold-Token header. Authorization is left for your app. See Auth.

ctx

Every handler gets ctx as its first argument:

Handler capabilities

Outbound fetch and server env need a claimed deploy. Claiming is coming soon, so today they work only in npx @aozumi/fold dev. An anonymous deploy rejects any server or shared file that mentions fetch.

Fold has no scheduler. To ingest data on a schedule, have an outside service call a writable endpoint. See Dashboard counts.

Errors

Throw an Error to fail a call. The message reaches the caller: useMutation and useAction promises reject with it, useQuery throws it during render (catch it with ErrorBoundary), and endpoints answer 500 with { "error": "<message>" }. Do not put secrets in error messages.