@abloatai/ablo 0.3.0

package/dist/schema/schema.js

@@ -0,0 +1,188 @@
+/**
+ * Schema Definition + Type Inference
+ *
+ * defineSchema() wraps your models. Types are inferred via Zod — no custom type system.
+ *
+ * Usage:
+ *   import { z } from 'zod';
+ *   import { defineSchema, model, relation } from '@ablo/sync-engine/schema';
+ *
+ *   const schema = defineSchema({
+ *     tasks: model({
+ *       title: z.string(),
+ *       status: z.enum(['todo', 'doing', 'done']).default('todo'),
+ *       projectId: z.string().optional(),
+ *     }, {
+ *       project: relation.belongsTo('projects', 'projectId'),
+ *     }),
+ *   });
+ *
+ *   type Task = InferModel<typeof schema, 'tasks'>;
+ */
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+function resolveCasing(fn) {
+    if (fn === undefined)
+        return (x) => x;
+    if (typeof fn === 'function')
+        return fn;
+    switch (fn) {
+        case 'snake_case':
+            return camelToSnake;
+        case 'camelCase':
+            return (x) => x;
+    }
+}
+/** Pure camelCase → snake_case. Matches postgres.fromCamel semantics but
+ * kept local so the SDK stays free of any driver dependency — consumers
+ * using Prisma/Drizzle/raw pg should all get the same result. */
+function camelToSnake(identifier) {
+    return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+/** Base fields every synced model gets automatically */
+const baseFieldsSchema = z.object({
+    id: z.string(),
+    createdAt: z.date(),
+    updatedAt: z.date(),
+    organizationId: z.string().optional(),
+    createdBy: z.string().optional(),
+});
+// ── Factory ───────────────────────────────────────────────────────────────
+/**
+ * Define a sync engine schema.
+ *
+ * ```ts
+ * const schema = defineSchema({
+ *   tasks: model({ title: z.string(), status: z.string().default('todo') }),
+ *   projects: model({ name: z.string() }),
+ * });
+ * ```
+ */
+/**
+ * Lowercase-first camelCase round-trip check. Must match the convention used
+ * by `postgres.camel` in the client driver (porsager/postgres), which is:
+ *
+ *   `content_json`       → `contentJson`  (snake → camel)
+ *   `contentJson`        → `content_json` (camel → snake)
+ *   `contentJSON`        → `content_j_s_o_n` (BROKEN — doesn't round-trip)
+ *
+ * Any field name that doesn't round-trip under this pair of transforms will
+ * silently fail to populate on the client: the wire delivers one casing,
+ * the dynamic class's constructor reads another, and the field lands as
+ * `undefined`. We catch it here so schema authors see an error at
+ * definition time rather than at runtime.
+ *
+ * Rule: a standard camelCase identifier has runs of one uppercase letter
+ * followed by lowercase letters — never two consecutive uppercase letters.
+ * `contentJSON` has `JSON` all-uppercase, so we reject it.
+ */
+function assertRoundTrippableCamelCase(modelName, fieldName) {
+    // Base fields merged in by defineSchema are already validated; skip.
+    if (fieldName === 'id')
+        return;
+    // Leading-lowercase constraint: fields must be camelCase, not PascalCase.
+    // PascalCase is reserved for typenames.
+    if (fieldName[0] >= 'A' && fieldName[0] <= 'Z') {
+        throw new AbloValidationError(`[defineSchema] ${modelName}.${fieldName}: field names must start lowercase ` +
+            `(camelCase). Use "${fieldName[0].toLowerCase()}${fieldName.slice(1)}" instead.`, { code: 'schema_field_not_camelcase' });
+    }
+    // Two-consecutive-uppercase check. The classic failure mode is
+    // `contentJSON`, `contentHTML`, `myURLParam`, etc. These don't round-trip
+    // through `postgres.camel` — the snake_case intermediate would be
+    // `content_j_s_o_n`, which is not a column that exists.
+    for (let i = 0; i < fieldName.length - 1; i++) {
+        const a = fieldName[i];
+        const b = fieldName[i + 1];
+        const aUpper = a >= 'A' && a <= 'Z';
+        const bUpper = b >= 'A' && b <= 'Z';
+        if (aUpper && bUpper) {
+            throw new AbloValidationError(`[defineSchema] ${modelName}.${fieldName}: two consecutive uppercase ` +
+                `letters ("${a}${b}") will not round-trip through the ` +
+                `snake_case ↔ camelCase transform used by the sync driver. ` +
+                `The wire delivers camelCase (lowercase after the first letter of ` +
+                `each word); a field named "${fieldName}" would never receive its ` +
+                `value and read as undefined on the client. Use standard ` +
+                `camelCase (e.g. "contentJson" instead of "contentJSON").`, { code: 'schema_field_consecutive_caps' });
+        }
+    }
+}
+export function defineSchema(models, options) {
+    // Build validators with base fields merged in, and resolve defaults for
+    // `typename` and `persist.store` so downstream code (the generic loader,
+    // the hydration pipeline, the Go named-query registry) can rely on these
+    // fields being set without re-deriving them at every call site.
+    //
+    // Defaults:
+    //   typename      ← schema key (e.g. `slideLayer` → `'slideLayer'`)
+    //   persist.store ← typename (only resolved when `persist` was provided)
+    //
+    // A consumer that passes `typename: 'SlideLayer'` explicitly (common when
+    // the wire shape uses PascalCase while the schema key is camelCase) keeps
+    // that value — the fallback only fires when the field is unset.
+    //
+    // The models record is rebuilt rather than mutated in place because
+    // `ModelDef`'s fields are `readonly`. The rebuild is a shallow spread per
+    // entry, so the inferred shape/relations/fields metadata references are
+    // preserved (no type inference regression at consumer call sites).
+    const validators = {};
+    const resolvedModels = {};
+    const casing = resolveCasing(options?.casing);
+    for (const [name, def] of Object.entries(models)) {
+        // Catch round-trip-hostile field names at definition time. Deferring
+        // this check to runtime means every affected field silently reads
+        // `undefined` on the client — and the author only notices when a UI
+        // that depends on the field goes blank. Throwing here makes the
+        // failure immediate and unambiguous.
+        for (const fieldName of Object.keys(def.shape)) {
+            assertRoundTrippableCamelCase(name, fieldName);
+        }
+        validators[name] = baseFieldsSchema.merge(def.schema);
+        // Resolve every relation's `foreignKeyColumn` once, now. The builder
+        // constructs each RelationDef with `foreignKeyColumn = foreignKey`
+        // (identity) so this is a no-op when `casing` is unset — existing
+        // consumers get the same behavior they had before the option landed.
+        // When `casing: 'snake_case'` is set, every FK flips to its
+        // snake_case DB column name here and nowhere else. Server-side SQL
+        // compilers read the resolved value directly.
+        for (const relName of Object.keys(def.relations)) {
+            const rel = def.relations[relName];
+            rel.foreignKeyColumn = casing(rel.foreignKey);
+        }
+        const typename = def.typename ?? name;
+        const persist = def.persist
+            ? { ...def.persist, store: def.persist.store ?? typename }
+            : undefined;
+        resolvedModels[name] = { ...def, typename, persist };
+    }
+    return {
+        // Cast back to S: we only added values to optional fields that were
+        // already part of ModelDef, so the shape is structurally unchanged.
+        models: resolvedModels,
+        validators: validators,
+        identityRoles: options?.identityRoles ?? [],
+    };
+}
+/**
+ * Compose the canonical sync-group set this identity is allowed to
+ * subscribe to, derived purely from the schema's registered
+ * {@link IdentityRole}s. Walks every role, calls its `extract` against
+ * the identity context, and substitutes each id into the role's
+ * `template`. Output is stable, deduped, and never includes a literal
+ * convention string from this function itself — the convention lives
+ * 100% in the consumer's schema declaration.
+ *
+ * Returns `[]` when the schema has no identity roles registered or
+ * when no role's extractor produces an id. Caller decides what to do
+ * with `[]`; the server's intersect-with-requested logic treats it as
+ * "no scope" rather than "match everything."
+ */
+export function composeIdentitySyncGroups(identity, schema) {
+    const out = new Set();
+    for (const role of schema.identityRoles) {
+        for (const id of role.extract(identity)) {
+            if (id)
+                out.add(role.template.replace('{id}', id));
+        }
+    }
+    return Array.from(out);
+}

package/dist/schema/sugar.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Intent-first shorthand for `model(...)` — the Modal-inspired DX layer.
+ *
+ * The factory verbs encode the two orthogonal axes that matter for
+ * safety and bootstrap behavior:
+ *
+ *   - **Writability** (axis 1): `mutable.*` means clients may send
+ *     CREATE/UPDATE/DELETE over the `commit` wire protocol.
+ *     `readOnly.*` means the model is server-managed — deltas stream
+ *     to clients but clients cannot mutate.
+ *   - **Load strategy** (axis 2): `.instant` loads at bootstrap,
+ *     `.lazy` loads on first access, `.manual` requires explicit
+ *     queries.
+ *
+ * The two-token form (`mutable.lazy({...})`) reads the safety intent
+ * in the first token and the load shape in the second — you know both
+ * key facts about the entity before scanning its fields.
+ *
+ * This is additive: the original `model(...)` factory keeps working.
+ * New entities should prefer the verbs; existing entities can migrate
+ * entity-by-entity.
+ *
+ * Example:
+ * ```ts
+ * // Before — 7 options to read before the fields make sense
+ * tasks: model({ title: z.string() }, { ... }, {
+ *   typename: 'Task', tableName: 'tasks', mutable: true,
+ *   load: 'lazy', lazyObservable: true, computed: tasksComputed,
+ * }),
+ *
+ * // After — intent reads off the verb; options carry only the
+ * // fields that actually diverge from defaults
+ * tasks: mutable.lazy({ title: z.string() }, {
+ *   typename: 'Task', tableName: 'tasks',
+ *   relations: { ... },
+ *   computed: tasksComputed,
+ * }),
+ * ```
+ */
+import type { z } from 'zod';
+import { type ModelDef, type ModelOptions, type ComputedRecord, type RelationRecord } from './model.js';
+/**
+ * Options accepted by every sugar verb. A strict subset of
+ * {@link ModelOptions} — anything the verb infers (`mutable`, `load`,
+ * `lazyObservable`) is deliberately absent so the call site can't
+ * contradict its verb.
+ */
+export interface SugarOptions<R extends RelationRecord = RelationRecord, C extends ComputedRecord = ComputedRecord> {
+    /** Relations to other models. Same shape as `model()`'s second arg. */
+    relations?: R;
+    /** Computed getters installed on the model class prototype. */
+    computed?: C;
+    /**
+     * Wire `__typename` (PascalCase, e.g. `'Task'`). Defaults to the schema
+     * key via `defineSchema` — override when the wire shape differs from
+     * the camelCase schema key.
+     */
+    typename?: string;
+    /**
+     * Actual Postgres table name. Override when Prisma's `@@map` diverges
+     * from the naive snake_case of the typename (e.g. `Member` maps to
+     * `'member'` singular, not `'members'`).
+     */
+    tableName?: string;
+    /**
+     * Whether the table has an `organization_id` column. Default: `true`.
+     * Set `false` for system-scoped tables (subscriptions, teams, etc.).
+     */
+    orgScoped?: boolean;
+    /**
+     * Scope rows via a parent table when this table has no
+     * `organization_id` column. See {@link ModelOptions.scopedVia}.
+     */
+    scopedVia?: ModelOptions['scopedVia'];
+    /**
+     * Template for participant scope derivation (e.g. `'matter:{id}'`).
+     * Omit for nested children whose access cascades from a parent.
+     */
+    syncGroupFormat?: string;
+    /** Max rows loaded during bootstrap. Only applies to `.instant`. */
+    bootstrapLimit?: number;
+    /** Bootstrap sort order (e.g. `'created_at DESC'`). */
+    bootstrapOrderBy?: string;
+    /** IndexedDB persistence hints — see {@link ModelOptions.persist}. */
+    persist?: ModelOptions['persist'];
+    /**
+     * Defer MobX observability to first access. Override the verb's
+     * default when a `.lazy` model is small enough that eager MobX setup
+     * is fine, or a `.instant` model is hot enough to justify deferral.
+     */
+    lazyObservable?: boolean;
+}
+/**
+ * Client-writable entities. `mutable.*` is the opt-in signal for wire
+ * mutations via `commit` — equivalent to setting
+ * `{ mutable: true, load: X }` on `model()`.
+ *
+ * Pick the load suffix by data-access pattern:
+ *   - `.instant`  — small, always-needed (Theme, Layout, StatusGroup)
+ *   - `.lazy`     — large collections fetched on first query
+ *     (SlideLayer, Message, Task)
+ *   - `.manual`   — never auto-loaded; explicit queries only
+ */
+export declare const mutable: {
+    instant: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+    lazy: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+    manual: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+};
+/**
+ * Server-managed entities. `readOnly.*` means clients subscribe to
+ * deltas but cannot emit mutations — any `commit` op for this model
+ * is rejected at the server with "Unknown model."
+ *
+ * Use for:
+ *   - Server-written state: `sync_deltas`, `presence`, version vectors
+ *   - Ingestion pipelines: digest entries, filing jobs
+ *   - Audit surfaces: anything where clients watch but only the server
+ *     writes
+ */
+export declare const readOnly: {
+    instant: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+    lazy: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+    /**
+     * Internal-only: never auto-loaded, never written by clients. The
+     * strongest safety posture — use for tables the SDK must know about
+     * (for type inference) but that should never flow over the wire.
+     */
+    internal: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+};

package/dist/schema/sugar.js

@@ -0,0 +1,94 @@
+/**
+ * Intent-first shorthand for `model(...)` — the Modal-inspired DX layer.
+ *
+ * The factory verbs encode the two orthogonal axes that matter for
+ * safety and bootstrap behavior:
+ *
+ *   - **Writability** (axis 1): `mutable.*` means clients may send
+ *     CREATE/UPDATE/DELETE over the `commit` wire protocol.
+ *     `readOnly.*` means the model is server-managed — deltas stream
+ *     to clients but clients cannot mutate.
+ *   - **Load strategy** (axis 2): `.instant` loads at bootstrap,
+ *     `.lazy` loads on first access, `.manual` requires explicit
+ *     queries.
+ *
+ * The two-token form (`mutable.lazy({...})`) reads the safety intent
+ * in the first token and the load shape in the second — you know both
+ * key facts about the entity before scanning its fields.
+ *
+ * This is additive: the original `model(...)` factory keeps working.
+ * New entities should prefer the verbs; existing entities can migrate
+ * entity-by-entity.
+ *
+ * Example:
+ * ```ts
+ * // Before — 7 options to read before the fields make sense
+ * tasks: model({ title: z.string() }, { ... }, {
+ *   typename: 'Task', tableName: 'tasks', mutable: true,
+ *   load: 'lazy', lazyObservable: true, computed: tasksComputed,
+ * }),
+ *
+ * // After — intent reads off the verb; options carry only the
+ * // fields that actually diverge from defaults
+ * tasks: mutable.lazy({ title: z.string() }, {
+ *   typename: 'Task', tableName: 'tasks',
+ *   relations: { ... },
+ *   computed: tasksComputed,
+ * }),
+ * ```
+ */
+import { model, } from './model.js';
+/** Internal helper — builds a ModelDef with baseline safety+load flags applied. */
+function build(shape, opts, baseline) {
+    return model(shape, (opts?.relations ?? {}), {
+        mutable: baseline.mutable,
+        load: baseline.load,
+        lazyObservable: opts?.lazyObservable ?? baseline.lazyObservable,
+        typename: opts?.typename,
+        tableName: opts?.tableName,
+        orgScoped: opts?.orgScoped,
+        scopedVia: opts?.scopedVia,
+        syncGroupFormat: opts?.syncGroupFormat,
+        bootstrapLimit: opts?.bootstrapLimit,
+        bootstrapOrderBy: opts?.bootstrapOrderBy,
+        persist: opts?.persist,
+        computed: opts?.computed,
+    });
+}
+/**
+ * Client-writable entities. `mutable.*` is the opt-in signal for wire
+ * mutations via `commit` — equivalent to setting
+ * `{ mutable: true, load: X }` on `model()`.
+ *
+ * Pick the load suffix by data-access pattern:
+ *   - `.instant`  — small, always-needed (Theme, Layout, StatusGroup)
+ *   - `.lazy`     — large collections fetched on first query
+ *     (SlideLayer, Message, Task)
+ *   - `.manual`   — never auto-loaded; explicit queries only
+ */
+export const mutable = {
+    instant: (shape, opts) => build(shape, opts, { mutable: true, load: 'instant', lazyObservable: false }),
+    lazy: (shape, opts) => build(shape, opts, { mutable: true, load: 'lazy', lazyObservable: true }),
+    manual: (shape, opts) => build(shape, opts, { mutable: true, load: 'manual', lazyObservable: true }),
+};
+/**
+ * Server-managed entities. `readOnly.*` means clients subscribe to
+ * deltas but cannot emit mutations — any `commit` op for this model
+ * is rejected at the server with "Unknown model."
+ *
+ * Use for:
+ *   - Server-written state: `sync_deltas`, `presence`, version vectors
+ *   - Ingestion pipelines: digest entries, filing jobs
+ *   - Audit surfaces: anything where clients watch but only the server
+ *     writes
+ */
+export const readOnly = {
+    instant: (shape, opts) => build(shape, opts, { mutable: false, load: 'instant', lazyObservable: false }),
+    lazy: (shape, opts) => build(shape, opts, { mutable: false, load: 'lazy', lazyObservable: true }),
+    /**
+     * Internal-only: never auto-loaded, never written by clients. The
+     * strongest safety posture — use for tables the SDK must know about
+     * (for type inference) but that should never flow over the wire.
+     */
+    internal: (shape, opts) => build(shape, opts, { mutable: false, load: 'manual', lazyObservable: true }),
+};