primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/db-codegen/dbTsTypes.js

@@ -0,0 +1,139 @@
+/**
+ * Map database-type TOML field/param types → TypeScript types for the
+ * `databases codegen` generator (issue #814).
+ *
+ * The record-interface half reuses the SAME `FieldType` vocabulary that
+ * powers the document-model codegen-v2 generator
+ * (`packages/js-bao/src/cli/v2/tsTypes.ts`): the database-type
+ * `[models.<m>.fields.<f>]` blocks round-trip through the same
+ * `loadSchemaFromTomlString` loader, so the field→TS mapping is identical
+ * (`string|id|date → string`, `number → number`, `boolean → boolean`,
+ * `stringset → StringSet`).
+ *
+ * The op-params half maps the operation `params.{type}` vocabulary
+ * (`string|number|boolean|object`, validated server-side in
+ * `database-type-operations-controller.ts`). `object` has no field-type
+ * analog and carries no nested schema, so it renders as `Record<string, unknown>`.
+ *
+ * NOTE (#842 — infer required record fields from operation params): when that
+ * issue is scheduled, the op-params analysis it needs (which fields a `$params.X`
+ * binding writes, and whether the param is `required`) already exists in
+ * `inferParamFieldTypes(op)` in
+ * `src/app-api/controllers/database-type-config-controller.ts` (issue #845 /
+ * #812 Phase 2). Its return shape was deliberately made growable (it can carry
+ * a `requiredInThisOp` flag) so it can be lifted into a shared `analyzeOpParams`
+ * pass consumed by BOTH the scaffold (#845, field *type*) and codegen (#842,
+ * field *required-ness*). Lift it rather than re-walking the ops here.
+ */
+import { arrayOf, atom, recordOf, tsStringLiteral, union, } from "../codegen-shared/prettierStable.js";
+/**
+ * Returns the TS type expression for a record field type. Unknown types
+ * fall back to `unknown` rather than throwing: the database-type TOML is
+ * author-curated and may legitimately carry a field type the CLI's vendored
+ * vocabulary predates, and a hard throw would block codegen for the whole
+ * file over one unrecognized field.
+ */
+export function tsTypeForDbFieldType(fieldType) {
+    switch (fieldType) {
+        case "string":
+        case "id":
+        case "date":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "stringset":
+            // StringSet serializes to a string array on the wire.
+            return "string[]";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Render a TypeScript string-literal union from an `enum` allowed-value set as
+ * a wrappable node (e.g. `["a", "b"]` → `"a" | "b"`; a long union renders as
+ * Prettier's leading-pipe form rather than one over-width line, #1565). Each
+ * value is emitted via `tsStringLiteral` so quotes, backslashes, and other
+ * special characters escape into a valid TS string literal AND the quote choice
+ * matches Prettier's (fewer-escapes rule), keeping the output a fixed point.
+ *
+ * Shared enum vocabulary with the doc-model v2 codegen
+ * (`packages/js-bao/src/cli/v2/tsTypes.ts`). The `enum` array is validated
+ * upstream by the TOML loader (`parseFieldOptions`): non-empty, all-string,
+ * string-field-only. This renderer assumes that contract has held.
+ */
+function unionNodeFromEnum(values) {
+    return union(values.map((v) => atom(tsStringLiteral(v))));
+}
+/**
+ * Returns the TS type expression for a record field as a wrappable node,
+ * honoring an optional string `enum` allowed-value set (#843). A non-empty
+ * `enum` on a `string` field renders a string-literal union (a long one in
+ * Prettier's leading-pipe form, #1565); otherwise falls back to the base
+ * `tsTypeForDbFieldType` mapping.
+ */
+export function typeNodeForDbField(fieldType, enumValues) {
+    if (fieldType === "string" &&
+        Array.isArray(enumValues) &&
+        enumValues.length > 0) {
+        return unionNodeFromEnum(enumValues);
+    }
+    return atom(tsTypeForDbFieldType(fieldType));
+}
+/**
+ * Returns the TS type expression for an op param as a wrappable node, honoring
+ * an optional string `enum` allowed-value set (#861). A non-empty `enum` on a
+ * `string` param renders a string-literal union (`"a" | "b"`; a long one in
+ * Prettier's leading-pipe form, #1565); otherwise falls back to the base
+ * param-type mapping below. Mirrors `typeNodeForDbField` (the record-field
+ * sibling) and reuses `unionNodeFromEnum` for a single escaping implementation.
+ *
+ * Unlike the record-field path (validated upstream by `parseFieldOptions`,
+ * which throws), op-param enum *shape* is validated server-side in
+ * `validateParams` at config-push time. So this renderer just falls back to
+ * the base type for a non-string param or an empty enum rather than throwing —
+ * the server is the source of truth for rejecting a malformed param `enum`.
+ */
+export function typeNodeForDbParamType(paramType, enumValues, items) {
+    // Array param (#1488): a declared `type = "array"` (Phase 2) or one inferred
+    // from a `$in`/`$nin` binding (Phase 1). `items` is the scalar element type;
+    // a per-element `enum` on a string-element array renders `("a" | "b")[]`.
+    // A missing/unresolved `items` renders `unknown[]` (the conservative widen).
+    if (paramType === "array") {
+        let elem;
+        if (items === "string" &&
+            Array.isArray(enumValues) &&
+            enumValues.length > 0) {
+            elem = unionNodeFromEnum(enumValues);
+        }
+        else if (items) {
+            // Element type is always scalar here, so the recursion never re-enters
+            // this array branch.
+            elem = typeNodeForDbParamType(items);
+        }
+        else {
+            elem = atom("unknown");
+        }
+        return arrayOf(elem);
+    }
+    if (paramType === "string" &&
+        Array.isArray(enumValues) &&
+        enumValues.length > 0) {
+        return unionNodeFromEnum(enumValues);
+    }
+    switch (paramType) {
+        case "string":
+            return atom("string");
+        case "number":
+        case "integer":
+            return atom("number");
+        case "boolean":
+            return atom("boolean");
+        case "object":
+            return recordOf("unknown");
+        default:
+            return atom("unknown");
+    }
+}
+//# sourceMappingURL=dbTsTypes.js.map

package/dist/src/lib/db-codegen/dbTsTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dbTsTypes.js","sourceRoot":"","sources":["../../../../src/lib/db-codegen/dbTsTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,eAAe,EACf,KAAK,GAEN,MAAM,qCAAqC,CAAC;AA8B7C;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI,CAAC;QACV,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,WAAW;YACd,sDAAsD;YACtD,OAAO,UAAU,CAAC;QACpB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,iBAAiB,CAAC,MAAgB;IACzC,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,UAAqB;IAErB,IACE,SAAS,KAAK,QAAQ;QACtB,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACzB,UAAU,CAAC,MAAM,GAAG,CAAC,EACrB,CAAC;QACD,OAAO,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAAiB,EACjB,UAAqB,EACrB,KAAc;IAEd,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,6EAA6E;IAC7E,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QAC1B,IAAI,IAAc,CAAC;QACnB,IACE,KAAK,KAAK,QAAQ;YAClB,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;YACzB,UAAU,CAAC,MAAM,GAAG,CAAC,EACrB,CAAC;YACD,IAAI,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,KAAK,EAAE,CAAC;YACjB,uEAAuE;YACvE,qBAAqB;YACrB,IAAI,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IACD,IACE,SAAS,KAAK,QAAQ;QACtB,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACzB,UAAU,CAAC,MAAM,GAAG,CAAC,EACrB,CAAC;QACD,OAAO,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IACD,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,KAAK,SAAS;YACZ,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC7B;YACE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/dist/src/lib/db-codegen/dbTypeIR.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared database-type operation IR (issue #1547, Phase 4).
+ *
+ * `describeDbType` resolves ONE database-type TOML into a naming-neutral
+ * descriptor of its record models and operations — the record fields (with
+ * inferred required-ness), the per-op input params, and the per-op result
+ * descriptor (query projection #1439, mutation, count, aggregate,
+ * applyToQuery, pipeline return #1437). It performs NO language-specific
+ * naming: the TS renderer (`dbGenerator.ts`) and the Swift renderer
+ * (`swift-codegen/dbGenerator.ts`) both consume this SAME IR and each apply
+ * their own identifier rules. Neither renderer re-walks the op definitions, so
+ * the two clients can never disagree on which operations a database type
+ * exposes, what params they take, or what shape they return (issue #1547
+ * binding item 5 — the same "shared operation IR, no metadata reconstruction"
+ * contract Phase 3's `describeWorkflowInvoker` gives the workflow invoker).
+ *
+ * The resolution logic here was lifted verbatim from `renderDbTypeFile`'s
+ * former inline body; the only change is that result descriptors reference a
+ * MODEL NAME (naming-neutral) rather than a resolved TS interface name, so the
+ * Swift renderer can map the same model to its own type name.
+ */
+import type { RecordField, ParamField, ProjectionClassification } from "./dbTemplates.js";
+export interface DbCodegenInput {
+    /** Database type name (drives the output filename). */
+    databaseType: string;
+    /** Path to the source `database-type-configs/<type>.toml` file. */
+    tomlPath: string;
+    /** Raw TOML content (already read from disk). */
+    tomlContent: string;
+}
+/**
+ * Naming-neutral form of a pipeline op's resolved `return` step (#1437). Same
+ * shape as `dbTemplates.PipelineReturnDescriptor` but keyed on the returning
+ * step's MODEL NAME instead of a resolved interface name, so each renderer maps
+ * it to its own record type. `opaque` → the generic pipeline-result envelope.
+ */
+export type PipelineReturnIR = {
+    kind: "query";
+    modelName: string | null;
+    projection: ProjectionClassification;
+} | {
+    kind: "count";
+} | {
+    kind: "aggregate";
+} | {
+    kind: "opaque";
+};
+/** One record model on a database type (read shape), naming-neutral. */
+export interface DbRecordIR {
+    /** TOML model name (e.g. `accounts`). */
+    modelName: string;
+    /** Optional `class_name` override from the schema (naming input). */
+    className?: string;
+    /**
+     * Record fields with required-ness already resolved (schema `required`,
+     * `id` auto-assign, and op-params inference #842 folded in). Rendered into a
+     * struct/interface member per field.
+     */
+    fields: RecordField[];
+}
+/** One operation on a database type, naming-neutral. */
+export interface DbOpIR {
+    /** Exact operation name (the `executeOperation` string argument). */
+    opName: string;
+    /** Operation type (`query|mutation|count|aggregate|pipeline|applyToQuery`). */
+    opType: string;
+    /** Declared input params (sorted by name), write shape. */
+    params: ParamField[];
+    /** Whether the op declares any params (a param-less op is callable bare). */
+    hasParams: boolean;
+    /**
+     * For a `query` op, the model its result rows are typed over — or null when
+     * the op has no model or the model has no record schema (the result falls
+     * back to an open/untyped row).
+     */
+    resultModelName: string | null;
+    /** For a `query` op, how its static `projection` narrows the record (#1439). */
+    projection?: ProjectionClassification;
+    /** For a `pipeline` op, the resolved `return`-step shape (#1437). */
+    pipelineReturn?: PipelineReturnIR;
+}
+/**
+ * One realtime subscription on a database type (#1544 Phase 2), naming-neutral.
+ *
+ * `modelName` is guaranteed to name a model that has a record schema on this
+ * type (`describeDbType` throws otherwise — a subscription can't be typed
+ * against a model the type doesn't declare; matches the server's
+ * `modelName is required` create validation). `select` fields, when present,
+ * are each guaranteed to be a known member of that record (declared field or
+ * stamped field) unless the record is the open `Record<string, unknown>` form,
+ * so the renderer can emit a valid `Pick<Record, …>` without a further guard.
+ */
+export interface DbSubscriptionIR {
+    /** Subscription key (the `subscribe()` string argument). */
+    subscriptionKey: string;
+    /** Model whose record type binds the delivered change payload. */
+    modelName: string;
+    /**
+     * Projected field names when the subscription declares `select` (→ the event
+     * record narrows to `Pick<Record, …fields>`), else null (→ the full record).
+     * Sorted + de-duplicated for deterministic output.
+     */
+    select: string[] | null;
+}
+/** The shared, naming-neutral descriptor of one database type. */
+export interface DbTypeIR {
+    /** Database type name (drives the output filename). */
+    databaseType: string;
+    /** Content fingerprint stamped in the generated header. */
+    fingerprint: string;
+    /** Server-stamped field names appended as OPTIONAL props on every record. */
+    stampedFields: string[];
+    /** Record models (schema order; renderers sort by their own type name). */
+    records: DbRecordIR[];
+    /** Operations, sorted by op name for deterministic output. */
+    ops: DbOpIR[];
+    /** Subscriptions, sorted by subscription key for deterministic output. */
+    subscriptions: DbSubscriptionIR[];
+}
+/**
+ * Resolve a database-type TOML into the shared, naming-neutral IR. Pure: no
+ * I/O beyond parsing the passed content. Both the TS and Swift renderers call
+ * this so their op/record metadata can never diverge.
+ */
+export declare function describeDbType(input: DbCodegenInput): DbTypeIR;
+/**
+ * Infer the scalar element type for op params consumed by a `$in`/`$nin`
+ * filter operator (#1488). See the original doc in `dbGenerator.ts` — moved
+ * here unchanged. Returns a map of param name → element TS type
+ * (`"unknown"` sentinel → widen to an untyped element).
+ */
+export declare function inferArrayParamElementTypes(op: any, fieldTypesByModel: Map<string, Map<string, string>>): Map<string, string>;
+/**
+ * Per-model result of {@link inferRequiredRecordFields}. Shaped as an object so
+ * it can grow additional inferred metadata later without changing callers.
+ */
+export interface InferredRecordModelInfo {
+    /** Record field names promoted to non-optional by op-params inference. */
+    fields: Set<string>;
+}
+/**
+ * Infer which record fields are always supplied at create time from `save` op
+ * params (#842). See the original doc in `dbGenerator.ts` — moved here
+ * unchanged.
+ */
+export declare function inferRequiredRecordFields(operations: any[]): Map<string, InferredRecordModelInfo>;