@abloatai/transaction 0.37.0

package/dist/schema/model.js

@@ -0,0 +1,124 @@
+/**
+ * Defines a model — one table's worth of fields, and one options object holding
+ * everything else the engine needs to know about it. A model is a Zod object schema
+ * paired with those options; the row type is inferred directly from Zod, with no
+ * separate type system to keep in sync.
+ *
+ * Usage:
+ *   import { z } from 'zod';
+ *   import { model, relation } from '@abloatai/transaction/schema';
+ *
+ *   const tasks = model({
+ *     title: z.string(),
+ *     status: z.enum(['todo', 'doing', 'done']).default('todo'),
+ *     projectId: z.string().optional(),
+ *   }, {
+ *     relations: { project: relation.belongsTo('projects', 'projectId') },
+ *     load: 'lazy',
+ *   });
+ */
+import { z } from 'zod';
+import { getFieldMeta, inferFieldMetaFromZod } from './field.js';
+// Tenancy lives in `tenancy.ts`. Authoring uses the `policy` option
+// (`PolicyInput`), which `resolvePolicy` normalizes into the canonical `Tenancy`
+// at build time.
+import { resolvePolicy } from './tenancy.js';
+import { DEFAULT_RESIDENCY } from './residency.js';
+/** Normalize the `entityRoles` option (single | array | undefined) to an array. */
+function normalizeEntityRoles(input) {
+    if (!input)
+        return undefined;
+    return Array.isArray(input) ? input : [input];
+}
+// ── Load strategies ───────────────────────────────────────────────────────
+// Defined in `./loadStrategy.ts`. Imported as well as re-exported: a bare
+// `export … from` would not bind the name for the `load` fields below.
+import { DEFAULT_LOAD_STRATEGY } from './loadStrategy.js';
+export { LoadStrategy, DEFAULT_LOAD_STRATEGY, loadsAtBootstrap } from './loadStrategy.js';
+// ── Model factory ─────────────────────────────────────────────────────────
+/**
+ * Defines a model from a Zod shape and its options. The row type is inferred from
+ * the shape; fields built with the {@link field} builders carry extra metadata,
+ * while plain Zod fields get metadata inferred from their Zod type. Everything else
+ * about the model — its {@link ModelOptions.relations}, its {@link LoadStrategy},
+ * the table it maps to — lives in the second argument, so a model that needs one
+ * setting never has to name the settings it does not use.
+ *
+ * ```ts
+ * import { z } from 'zod';
+ * import { model, relation } from '@abloatai/transaction/schema';
+ *
+ * // Fields alone
+ * const tags = model({ label: z.string() });
+ *
+ * // Loaded at bootstrap (the default), with an edge to its project
+ * const tasks = model({
+ *   title: z.string(),
+ *   status: z.enum(['todo', 'doing', 'done']).default('todo'),
+ *   projectId: z.string().optional(),
+ * }, {
+ *   relations: { project: relation.belongsTo('projects', 'projectId') },
+ * });
+ *
+ * // Loaded on first access
+ * const blocks = model({ sectionId: z.string(), type: z.string() }, {
+ *   relations: { section: relation.belongsTo('sections', 'sectionId') },
+ *   load: 'lazy',
+ * });
+ * ```
+ */
+export function model(shape, options) {
+    // Build the fields metadata record by walking the Zod shape.
+    // Fields built with `field.*()` have structured metadata; fields built
+    // with raw Zod get a fallback derived from the Zod typeName.
+    const fields = {};
+    for (const [name, zodType] of Object.entries(shape)) {
+        const meta = getFieldMeta(zodType);
+        if (meta) {
+            fields[name] = meta;
+        }
+        else {
+            fields[name] = inferFieldMetaFromZod(zodType);
+        }
+    }
+    return {
+        schema: z.object(shape),
+        shape,
+        fields,
+        relations: (options?.relations ?? {}),
+        load: options?.load ?? DEFAULT_LOAD_STRATEGY,
+        bootstrapLimit: options?.bootstrapLimit,
+        bootstrapOrderBy: options?.bootstrapOrderBy,
+        typename: options?.typename,
+        persist: options?.persist,
+        tableName: options?.tableName,
+        // Normalize the `policy` option into the canonical tenancy descriptor (defaults
+        // to a row-local organization column).
+        tenancy: resolvePolicy(options?.policy),
+        plane: options?.plane ?? DEFAULT_RESIDENCY,
+        // Unpack the `groups` option into the individual routing fields the server reads.
+        scope: options?.groups?.root,
+        grants: options?.groups?.grants,
+        entityRoles: normalizeEntityRoles(options?.groups?.roles),
+        // The conflict disposition is already plain data, so it passes through unchanged.
+        conflict: options?.conflict,
+        mutable: options?.mutable ?? true,
+        lazyObservable: options?.lazyObservable,
+        computed: options?.computed,
+        autoFill: options?.autoFill,
+        requiredFields: options?.requiredFields,
+    };
+}
+/**
+ * Returns the sync-group kind a scope-root model produces, or `undefined` when the
+ * model is not a scope root. `scope: true` derives the kind from the lowercased
+ * typename (`ReportSection` → `reportsection`); `scope: 'section'` sets it explicitly, which
+ * you use when the wire kind must differ from the typename. This is the single place
+ * that decides a record's own group, so every layer that reads it agrees.
+ */
+export function scopeKindOf(def, fallbackKey) {
+    if (!def.scope)
+        return undefined;
+    return (typeof def.scope === 'string' ? def.scope : (def.typename ?? fallbackKey)).toLowerCase();
+}
+//# sourceMappingURL=model.js.map

package/dist/schema/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/schema/model.ts"],"names":[],"mappings":"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"}

package/dist/schema/openapi.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Two OpenAPI 3.1 documents describing the same API, for two different readers.
+ *
+ * The server registers ONE parameterised route family — `/api/v1/models/:model`
+ * and what hangs below it, plus the coordination, credential and commit
+ * resources. The count does not move when a tenant's schema does.
+ * Authentication is a single Bearer scheme, your API key.
+ *
+ * {@link abloOpenApi} publishes that family. It takes no schema, so it cannot
+ * grow with one: identical for every caller, stable across every push, and the
+ * document a Python or Go client is generated from once. `spec-covers-routes`
+ * holds it to the served surface in both directions, so this is the list of
+ * routes rather than a description of it.
+ *
+ * {@link schemaToOpenApi} expands the model half into one set per model, with
+ * payloads typed from each model's introspectable {@link FieldMeta}. Five paths
+ * per model, regenerated on every push — worth it when you want generated types
+ * for one schema, and the wrong thing to hand an agent.
+ *
+ * Both return a plain JSON-serializable object; feed either into codegen (for
+ * example `ablo openapi > openapi.json`) or serve it directly.
+ */
+import type { Schema, SchemaRecord } from './schema.js';
+/** Options for {@link schemaToOpenApi} — the metadata stamped into the generated spec. */
+export interface SchemaToOpenApiOptions {
+    /** Spec title. Default `"Ablo API"`. */
+    readonly title?: string;
+    /** Spec version. Default `"1.0.0"`. */
+    readonly version?: string;
+    /** API base URL. Default `"https://api.abloatai.com/api"`. */
+    readonly serverUrl?: string;
+}
+type Json = Record<string, unknown>;
+/**
+ * The protocol reference: the route templates the server actually serves.
+ *
+ * This takes no schema, and that is the point. The server registers one
+ * parameterised route family (`/api/v1/models/:model/...`), so the surface is
+ * the same size no matter how many models a tenant defines — and a spec that
+ * cannot see a schema cannot grow with one. It is publishable once, identical
+ * for every caller, and stable across every schema push: the document a Python
+ * or Go client is generated from, and the surface an agent is handed.
+ *
+ * Payload shapes are generic here by design. A caller that wants them typed
+ * either reads the schema at runtime or generates the per-tenant expansion with
+ * {@link schemaToOpenApi}.
+ */
+export declare function abloOpenApi(options?: SchemaToOpenApiOptions): Json;
+/**
+ * The per-tenant expansion: every model's routes written out with typed payloads.
+ *
+ * Useful when you want generated types for one schema — five paths per model, so
+ * it grows with the schema and is regenerated on every push. It documents the
+ * same five routes {@link abloOpenApi} describes; it does not describe a
+ * different API.
+ */
+export declare function schemaToOpenApi<S extends SchemaRecord>(schema: Schema<S>, options?: SchemaToOpenApiOptions): Json;
+export {};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/schema/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/schema/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAyCxD,0FAA0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAoJpC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,sBAA2B,GAAG,IAAI,CA4UtE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,GAAE,sBAA2B,GACnC,IAAI,CA6EN"}