TypeScript SDK

@pylonsync/sdk is the foundation every other JS package depends on. It’s two things in one package:

A schema DSL for declaring entities, queries, actions, policies in TypeScript instead of editing pylon.manifest.json by hand.
The codegen runtime that compiles your TS schema into the manifest the Pylon server reads.

There’s no HTTP client in this package — for that, use @pylonsync/react (browser) or @pylonsync/sync (any JS host).

Install

bun add @pylonsync/sdk

npm install @pylonsync/sdk

pnpm add @pylonsync/sdk

Defining your schema

Create app.ts:

import {
  buildManifest,
  entity,
  field,
  query,
  action,
  policy,
} from "@pylonsync/sdk";

const User = entity("User", {
  email:        field.string().unique(),
  displayName:  field.string(),
  passwordHash: field.string().serverOnly().optional(),
  createdAt:    field.datetime().defaultNow(),
});

const Todo = entity("Todo", {
  title:    field.string(),
  done:     field.bool().default(false),
  authorId: field.id("User"),
  createdAt:field.datetime().defaultNow(),
}, {
  indexes: [{ name: "by_author", fields: ["authorId"] }],
});

const todosByAuthor = query("todosByAuthor", {
  input: [{ name: "authorId", type: "id(User)" }],
});

const createTodo = action("createTodo", {
  input: [
    { name: "title", type: "string" },
    { name: "authorId", type: "id(User)" },
  ],
});

const todoPolicy = policy({
  entity:     "Todo",
  allowRead:  "auth.userId != null && data.authorId == auth.userId",
  allowWrite: "auth.userId == data.authorId",
});

export default buildManifest({
  name: "todo-app",
  version: "0.1.0",
  entities:  [User, Todo],
  queries:   [todosByAuthor],
  actions:   [createTodo],
  policies:  [todoPolicy],
  routes:    [],
});

Fields are built with the field helper (field.string(), field.int(), field.id("User"), …) and refined with chained modifiers (.unique(), .optional(), .default(v), .defaultNow(), .owner(), .serverOnly(), .crdt(...)). query / action register a name plus a typed input list; the handler itself lives in a functions/*.ts file (see Actions). Then run codegen to materialize the manifest:

pylon codegen app.ts --out pylon.manifest.json

pylon dev does this automatically on file change.

Field types

DSL	Wire type	Notes
`field.string()`	`string`	UTF-8 text
`field.int()`	`number`	64-bit signed
`field.float()` (`field.number()`)	`number`	64-bit float
`field.bool()` (`field.boolean()`)	`boolean`
`field.datetime()`	`string`	ISO 8601
`field.richtext()`	`string`	LoroText by default; rich text in Studio
`field.id("User")`	`string`	Reference to another entity
`field.enum(["a", "b"])`	`string`	Codegen emits a literal union

Modifiers are chained methods, not option objects:

field.string().unique()          // enforce uniqueness
field.string().optional()        // nullable
field.bool().default(false)      // static insert-time default
field.datetime().defaultNow()    // stamp now() on insert
field.string().owner()           // stamp the row owner from the session
field.string().serverOnly()      // read on the server, never serialized to clients

For CRDT-backed fields, use .crdt(annotation):

field.string().crdt("text")    // LoroText — collaborative text (or field.richtext())
field.int().crdt("counter")    // LoroCounter — multi-writer increments

"text" and "counter" are wired end-to-end; the "list", "movable-list", and "tree" annotations are reserved (wire format locked in, server-side projection still landing). CRDT-backed fields don’t go through normal LWW merge; they sync via the binary CRDT broadcast channel. See Loro for the full picture.

Indexes

entity("Todo", {
  authorId: field.id("User"),
  status:   field.string(),
  createdAt:field.datetime().defaultNow(),
}, {
  indexes: [
    { name: "by_author",        fields: ["authorId"] },
    { name: "by_status_date",   fields: ["status", "createdAt"] },
    { name: "unique_slug",      fields: ["slug"], unique: true },
  ],
});

The first matching prefix on a multi-column index wins for query planning. Pylon translates these to native SQLite/Postgres indexes.

Search config

entity("Post", {
  title:    field.string(),
  body:     field.richtext(),
  tags:     field.string(),
  authorId: field.id("User"),
}, {
  search: {
    text:     ["title", "body"],
    facets:   ["authorId", "tags"],
    sortable: ["createdAt", "viewCount"],
  },
});

This wires the entity into the search plugin. Once enabled, the entity is queryable via POST /api/search/Post.

Relations

import { entity, field, relation } from "@pylonsync/sdk";

const Post = entity("Post", {
  title:    field.string(),
  authorId: field.id("User"),
}, {
  relations: [
    // name = accessor on the parent, target = entity, field = the FK on the target
    relation({ name: "comments", target: "Comment", field: "postId", many: true }),
  ],
});

const Comment = entity("Comment", {
  postId: field.id("Post"),
  body:   field.string(),
});

Relations enable include joins on queries. On the client, request them through the query’s include map (an object keyed by relation name):

import { db } from "@pylonsync/react";

const { data: posts } = db.useQuery("Post", { include: { comments: {} } });
// each post.comments is a Comment[]

Queries

Named, typed query inputs. Each input entry is { name, type, optional? }, where type is a field-type string ("string", "int", `id(User)`, …). Resolve to /api/query/<name>:

const recentTodos = query("recentTodos", {
  input: [{ name: "limit", type: "int", optional: true }],
});

const todosByAuthor = query("todosByAuthor", {
  input: [{ name: "authorId", type: "id(User)" }],
});

query / action register the name + input contract; the handler lives in a functions/<name>.ts file. Use a query() handler for reads and a mutation() / action() handler for writes and computed results.

Actions

Server-side functions with typed args. Resolve to /api/fn/<name>:

const completeTodo = action("completeTodo", {
  input: [{ name: "todoId", type: "id(Todo)" }],
});

The action’s handler lives in a separate file (functions/completeTodo.ts) and the function runtime wires it up:

// functions/completeTodo.ts
import { mutation, v } from "@pylonsync/functions";

export default mutation({
  args: { todoId: v.string() },
  async handler(ctx, args) {
    if (!ctx.auth.userId) throw new Error("sign in required");
    const todo = await ctx.db.get("Todo", args.todoId);
    if (!todo || todo.authorId !== ctx.auth.userId) throw new Error("forbidden");
    await ctx.db.update("Todo", args.todoId, { done: true });
  },
});

See Functions for the full handler API.

Policies

policy({
  entity:      "Todo",
  allowRead:   "auth.userId != null && data.authorId == auth.userId",
  allowInsert: "auth.userId == data.authorId",
  allowUpdate: "auth.userId == data.authorId",
  allowDelete: "auth.userId == data.authorId || auth.hasRole('admin')",
})

Each rule is a per-operation gate: allowRead, allowInsert, allowUpdate, allowDelete. allowWrite is a shared fallback for the three write ops, and allow is the fallback for all four. Expression syntax in RBAC.

Plugins

definePlugin({ name, hooks }) returns a PluginDefinition — a named set of server-side entity lifecycle hooks:

import { definePlugin } from "@pylonsync/sdk";

const audit = definePlugin({
  name: "audit",
  hooks: {
    // Return modified data to rewrite the row, or null to abort the write.
    beforeInsert: (entity, data) => ({ ...data, createdVia: "api" }),
    afterUpdate:  (entity, id, data) => console.log(`${entity} ${id} updated`),
  },
});

Available hooks: beforeInsert, afterInsert, beforeUpdate, afterUpdate, beforeDelete, afterDelete. Many capabilities don’t need a plugin at all — they’re declarative: full-text search is an entity’s search: option (above), and auth / scheduled jobs are configured with the auth() / cron() helpers passed to buildManifest.

Manifest output

buildManifest({...}) returns a Manifest object. The codegen step writes it to JSON:

// pylon.manifest.json (generated)
{
  "manifest_version": 1,
  "name": "todo-app",
  "version": "0.1.0",
  "entities":  [...],
  "routes":    [...],
  "queries":   [...],
  "actions":   [...],
  "policies":  [...],
  "auth":      { ... }
}

The Pylon server reads only the JSON — your TS source isn’t needed at runtime. This is what lets the same backend serve clients in any language.

Where to next

Browser clients → @pylonsync/react
Mobile → @pylonsync/react-native or Swift
Server-rendered → @pylonsync/next
Sync engine on its own → @pylonsync/sync

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

TypeScript SDK

Install

Defining your schema

Field types

Indexes

Search config

Relations

Queries

Actions

Policies

Plugins

Manifest output

Where to next

​Install

​Defining your schema

​Field types

​Indexes

​Search config

​Relations

​Queries

​Actions

​Policies

​Plugins

​Manifest output

​Where to next

Install

Defining your schema

Field types

Indexes

Search config

Relations

Queries

Actions

Policies

Plugins

Manifest output

Where to next