primitive-admin 1.1.0-alpha.9 → 1.1.0

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

@@ -0,0 +1,272 @@
+/**
+ * Pure string templates for the `databases codegen` generator (issue #814).
+ *
+ * FORMATTING CONTRACT (#1565): the emitted TypeScript must be a fixed point of
+ * Prettier's DEFAULT config — `prettier --write` over a generated file must
+ * leave it byte-for-byte unchanged, because `--check` byte-compares. There is
+ * no Prettier dependency and no automated round-trip test to catch a
+ * regression, so any edit here that changes line shapes must be verified by
+ * hand (regenerate a representative output, run Prettier over it, confirm no
+ * diff). Wrap long constructs through `codegen-shared/prettierStable.ts` rather
+ * than hand-joining strings — see that file's header for the full contract.
+ *
+ * Mirrors the codegen-v2 template style
+ * (`packages/js-bao/src/cli/v2/templates.ts`): total functions (no I/O, no
+ * hidden state), an auto-generated banner + fingerprint header, and
+ * deterministic ordering so `--check` can compare byte-for-byte.
+ *
+ * Diverges from codegen-v2 in two ways:
+ *   1. Database-DO records are schemaless documents, NOT `BaseModel` ORM
+ *      classes — so we emit plain `export interface` types with no class
+ *      shell, no barrel registration, and `import type` only.
+ *   2. We add an OPERATIONS half codegen-v2 has no analog for: per-op
+ *      input-params interfaces + per-op result aliases. The alias for an op
+ *      is derived from `op.type` AND, where it matters, the op's parsed
+ *      `definition`: a query op's `projection` (#1439), a mutation op's step
+ *      kinds (#1438), and a pipeline op's `return` step (#1437). The generator
+ *      resolves those into the small descriptors below; the templates stay pure
+ *      string-emitters.
+ */
+import { type TypeNode } from "../codegen-shared/prettierStable.js";
+/** A field on a record interface (read shape). */
+export interface RecordField {
+    name: string;
+    /** TOML field type (`string|number|boolean|date|id|stringset`). */
+    type: string;
+    /** Required props render as `name: T`; otherwise `name?: T`. */
+    required: boolean;
+    /**
+     * Allowed-value set for a `string` field (#843). When non-empty, the field
+     * renders a TS string-literal union (`"a" | "b"`) instead of bare `string`.
+     */
+    enum?: string[];
+}
+export interface RenderRecordInterfaceInput {
+    /** PascalCase interface name (e.g. `Account`). */
+    interfaceName: string;
+    /** TOML model name (e.g. `accounts`). */
+    modelName: string;
+    fields: RecordField[];
+    /**
+     * Server-stamped field names (timestamps + auto-populated fields) that
+     * appear on the READ record interface as OPTIONAL props, and only if not
+     * already declared in `fields`.
+     */
+    stampedFields: string[];
+}
+/** One declared param on an op-input interface (write shape). */
+export interface ParamField {
+    name: string;
+    /** TOML param type (`string|number|boolean|object|array`). */
+    type: string;
+    required: boolean;
+    /**
+     * Allowed-value set for a `string` param → string-literal union (#861).
+     * Validated server-side (`validateParams`) at config-push time; the emitter
+     * renders the union when present and falls back to the base type otherwise.
+     */
+    enum?: string[];
+    /**
+     * Scalar element type for an `array` param (#1488), either declared
+     * (`type = "array"` + `items = "..."`) or inferred from a `$in`/`$nin`
+     * binding. Undefined on a non-array param, or on an array whose element type
+     * could not be resolved (renders `unknown[]`).
+     */
+    items?: string;
+}
+export interface RenderOpParamsInterfaceInput {
+    /** PascalCase params interface name (e.g. `SaveAccountParams`). */
+    interfaceName: string;
+    /** Operation name (e.g. `saveAccount`). */
+    opName: string;
+    params: ParamField[];
+}
+/**
+ * How a query op's static `projection` narrows its record type (#1439). The
+ * generator resolves the projection against the model's record fields (guarding
+ * unknown / nested keys) and hands the template one of these; the template only
+ * assembles the `Pick`/`Partial` string.
+ *   - `full`    → `QueryResult<M>` (no projection, empty `{}`, or no schema).
+ *   - `pick`    → `QueryResult<Pick<M, ...fields>>` (inclusion; `id` folded in).
+ *   - `omit`    → `QueryResult<Omit<M, ...fields>>` (static all-exclusion over
+ *                 known schema fields, minus `id`/`type`). The DO strips excluded
+ *                 fields server-side (#1493 / issue #1456), so the excluded fields
+ *                 are genuinely absent from the result and `Omit` is truthful.
+ *   - `partial` → `QueryResult<Partial<M>>` (dynamic / mixed / unknown-key /
+ *                 nested-key exclusion — the honest fallback when the excluded set
+ *                 can't be resolved to known members; #1439/Codex-P2).
+ */
+export type ProjectionClassification = {
+    kind: "full";
+} | {
+    kind: "pick";
+    fields: string[];
+} | {
+    kind: "omit";
+    fields: string[];
+} | {
+    kind: "partial";
+};
+/**
+ * A `pipeline` op's resolved `return` step (#1437). The runtime flattens a
+ * returning pipeline to the returned step's shape, so codegen types it as that
+ * step's result. `return: "all"`, no `return`, or any step the generator can't
+ * resolve fall back to `opaque` → the generic `PipelineResult`.
+ */
+export type PipelineReturnDescriptor = {
+    kind: "query";
+    recordInterfaceName: string | null;
+    projection?: ProjectionClassification;
+} | {
+    kind: "count";
+} | {
+    kind: "aggregate";
+} | {
+    kind: "opaque";
+};
+export interface RenderOpResultAliasInput {
+    /** Per-op result alias name (e.g. `SaveAccountResult`). */
+    aliasName: string;
+    /** Operation name (e.g. `saveAccount`). */
+    opName: string;
+    /** Operation type (`query|mutation|count|aggregate|pipeline|applyToQuery`). */
+    opType: string;
+    /**
+     * For `query` ops, the record interface name the result is generic over
+     * (`QueryResult<Account>`). Null when the op's model has no record
+     * interface (e.g. pipeline) — falls back to `QueryResult<Record<string, unknown>>`.
+     */
+    recordInterfaceName: string | null;
+    /**
+     * For `query` ops (#1439), how the op's `projection` narrows the record type.
+     * Absent → treated as `full`.
+     */
+    projection?: ProjectionClassification;
+    /**
+     * For `pipeline` ops (#1437), the resolved `return`-step descriptor. Absent
+     * or `opaque` → the generic `PipelineResult`.
+     */
+    pipelineReturn?: PipelineReturnDescriptor;
+}
+/**
+ * The shared generic result shapes referenced by the per-op aliases. These
+ * mirror the runtime result shapes produced by the database-operations
+ * controller; per-op aliases point at them (and, where the definition makes the
+ * shape derivable, at a narrowed form — see `renderOpResultAlias`).
+ */
+export declare const RESULT_ALIASES_BLOCK = "// Generic per-op result shapes. These mirror the runtime result shapes\n// produced by the database-operations controller; per-op aliases reference\n// them (or a narrowed form when the op definition makes the shape derivable).\n\n/** `query` ops return a page of records. */\nexport interface QueryResult<T = Record<string, unknown>> {\n  data: T[];\n  hasMore?: boolean;\n  nextCursor?: string;\n}\n\n/**\n * One step's result inside a `mutation` op's uniform response (#1458).\n * `op` is the step kind; `id` is the record id (the resolved canonical id for\n * `upsertOn` saves). `values` carries an `increment` step's post-increment\n * counters; `error` a per-step failure string.\n */\nexport interface MutationStepResult {\n  op: \"save\" | \"patch\" | \"delete\" | \"increment\" | \"addToSet\" | \"removeFromSet\";\n  success: boolean;\n  id: string;\n  values?: Record<string, number>;\n  error?: string;\n}\n\n/**\n * Every `mutation` op returns a uniform `{ results: MutationStepResult[] }`\n * in DEFINITION-STEP order \u2014 one entry per step, tagged with its `op` kind and\n * record `id` (#1458). This is a SUCCESS-PATH guarantee: a step that fails at\n * the HTTP level surfaces as an error, and committed sibling writes in the same\n * op are not reported (the ops are not yet executed atomically \u2014 see #1478).\n */\nexport interface MutationResult {\n  results: MutationStepResult[];\n}\n\n/** `count` ops return a single count. */\nexport interface CountResult {\n  count: number;\n}\n\n/** `aggregate` ops return a single result object. */\nexport interface AggregateResult {\n  result: Record<string, unknown>;\n}\n\n/** `applyToQuery` ops return match/affect/fail counts. */\nexport interface ApplyToQueryResult {\n  matched: number;\n  affected: number;\n  failed: number;\n  sample?: unknown[];\n}\n\n/** `pipeline` ops return per-step results keyed by step name. */\nexport interface PipelineResult {\n  steps: Record<string, unknown>;\n}\n";
+/**
+ * Render the header (banner + regen hint + fingerprint).
+ */
+export declare function renderHeader(fingerprint: string): string;
+/**
+ * Render a single record interface (read shape). Stamped fields
+ * (`createdAt`, `modifiedAt`, `ownerId`, …) are appended as OPTIONAL props
+ * if not already present in `fields`.
+ */
+export declare function renderRecordInterface(input: RenderRecordInterfaceInput): string;
+/**
+ * Render a single op-input-params interface (write shape). `required: true`
+ * params are non-optional; others are optional. `object` params render as
+ * `Record<string, any>`.
+ */
+export declare function renderOpParamsInterface(input: RenderOpParamsInterfaceInput): string;
+/** A `Pick`/`Omit` key union (`"a" | "b"`), wrappable when it gets long. */
+export declare function fieldNameUnion(fields: string[]): TypeNode;
+/**
+ * Render a per-op result alias. The alias is derived from `op.type` and, where
+ * the shape is derivable from the parsed op definition, a narrowed form:
+ *   - `query`    → `QueryResult<M>`, narrowed by the op `projection` (#1439).
+ *   - `mutation` → `MutationResult` — every mutation op returns the uniform
+ *                  `{ results: MutationStepResult[] }` in definition order (#1458).
+ *   - `pipeline` → the returned step's result type (#1437); `return: "all"` /
+ *                  no-return / unresolvable keep the generic `PipelineResult`.
+ */
+export declare function renderOpResultAlias(input: RenderOpResultAliasInput): string;
+/** One operation the typed-ops factory exposes as a method (#1441). */
+export interface OpsFactoryOp {
+    /**
+     * Object-literal property key for the method — bare (`getX`) for a plain JS
+     * identifier, or a quoted string (`"get-x"`, `"delete"`) for a hyphenated /
+     * reserved-word / leading-digit op name. Produced by `objectPropertyKey`.
+     */
+    propertyKey: string;
+    /** Exact operation name passed as the `executeOperation` string argument. */
+    opName: string;
+    /** The op's `<Op>Params` interface name (write shape). */
+    paramsInterfaceName: string;
+    /** The op's `<Op>Result` alias name (read shape). */
+    resultAliasName: string;
+    /**
+     * Whether the op declares any params. A param-less op yields a method callable
+     * with no arguments (`ops.foo()`); its only arg is the optional `options`.
+     */
+    hasParams: boolean;
+}
+export interface RenderOpsFactoryInput {
+    /** Factory function name (e.g. `securitiesRefOps`). */
+    factoryName: string;
+    /** Database type name, for the doc comment. */
+    databaseType: string;
+    /** Operations to expose, in deterministic (name-sorted) order. */
+    ops: OpsFactoryOp[];
+}
+/**
+ * Render the typed-operations factory (#1441): an inlined structural client
+ * interface + a shared call-options type + the `export function <type>Ops`
+ * factory. Each method pairs an op's `<Op>Params` input with its `<Op>Result`
+ * output and calls `client.databases.executeOperation<<Op>Result>(...)`, so the
+ * generated code carries no `as` cast and no import — the real `JsBaoClient`
+ * satisfies the structural `OpsClient` param.
+ *
+ * Returns "" for a database type with no operations, so the caller can omit the
+ * factory entirely rather than emit an empty function.
+ */
+export declare function renderOpsFactory(input: RenderOpsFactoryInput): string;
+/** One subscription the typed-subscriptions factory exposes as a method. */
+export interface SubscriptionFactoryEntry {
+    /**
+     * Object-literal property key for the method — bare (`myTasks`) or a quoted /
+     * computed key for a non-identifier subscription key. Produced by
+     * `objectPropertyKey`.
+     */
+    propertyKey: string;
+    /** Exact subscription key string passed to `subscribe`. */
+    subscriptionKey: string;
+    /**
+     * The record type bound to the change payload — a record interface name
+     * (`Task`) or a projection (`Pick<Task, "id" | "name">`) when the
+     * subscription declares `select`. A `TypeNode` (not a pre-joined string) so
+     * `SubscribeOptions<...>` and the `subscribe<...>` type argument break the way
+     * Prettier would when a projection pushes the line past the print width
+     * (built by the generator via `fieldNameUnion`, mirroring `queryResultGeneric`).
+     */
+    eventType: TypeNode;
+}
+export interface RenderFactoriesInput {
+    /** Database type name, for the doc comments. */
+    databaseType: string;
+    /** Name of the `<type>Ops` factory function. */
+    opsFactoryName: string;
+    /** Name of the `<type>Subscriptions` factory function. */
+    subscriptionsFactoryName: string;
+    /** Operations to expose, in deterministic (name-sorted) order. */
+    ops: OpsFactoryOp[];
+    /** Subscriptions to expose, in deterministic (key-sorted) order. */
+    subscriptions: SubscriptionFactoryEntry[];
+}
+/**
+ * Render the typed-ops factory (#1441) and the typed-subscriptions factory
+ * (#1544 Phase 2) for one database type, sharing a single structural `OpsClient`
+ * interface (Fork 4 = A).
+ *
+ * With no subscriptions this is byte-identical to {@link renderOpsFactory}, so
+ * every existing generated file (none of which has subscriptions) is unchanged.
+ * When subscriptions exist, the shared `OpsClient` gains a `subscribe<T>`
+ * member, the inlined subscribe types are emitted once, and a separate
+ * `<type>Subscriptions` factory follows the ops factory. The file stays
+ * import-free (behavior 10).
+ *
+ * Returns "" when the type has neither ops nor subscriptions.
+ */
+export declare function renderFactories(input: RenderFactoriesInput): string;