primitive-admin 1.1.0-alpha.74 → 1.1.0-alpha.76

package/dist/src/lib/function-db-types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The typed database handle's generated declarations — #3182 phase 4.
+ *
+ * The intent settles what the handle is before unified-schemas: "generated at
+ * push time from the database type's TOML schema (js-bao's
+ * `loadSchemaFromTomlString`; not the client's runtime Yjs discovery): model
+ * names and field types in phase 2". So this is a THIRD renderer over the same
+ * `describeDbType` IR the TypeScript and Swift client generators already share
+ * — not a second parser and not a second idea of what a model is. Inline
+ * filter typing waits for unified-schemas, as the intent says.
+ *
+ * ── Why three files, in `functions/` ─────────────────────────────────────
+ *
+ * A generated declaration nothing loads is decoration (D3182-006). Function
+ * sources live under an environment- and app-specific config-tree path, the
+ * CLI's esbuild step never typechecks, and a project's own `tsconfig.json`
+ * commonly includes only `src`. So `config push` writes, beside the sources it
+ * serves:
+ *
+ *   - `primitive-db-types.d.ts` — the app's database types, and the module
+ *     augmentation that binds them to `ctx.db`;
+ *   - `primitive-functions.d.ts` — the SDK's own types. The package is not on
+ *     npm yet, and even when it is, a config tree is not an npm project:
+ *     without this the bare `primitive-functions` specifier every function
+ *     imports would not resolve at all, and the augmentation would have
+ *     nothing to augment;
+ *   - `tsconfig.json` — the wiring, so an editor and a bare `tsc` both see all
+ *     three with nothing for an author to configure.
+ *
+ * The two `.d.ts` files are GENERATED and rewritten on every push. The tsconfig
+ * is SCAFFOLDED once and then left to its author, because it is the file an
+ * author has a legitimate reason to adjust — with one exception: the two facts
+ * that make the wiring work at all (the `primitive-functions` path mapping and
+ * the declarations being in the program) are repaired when they are missing,
+ * so a tsconfig written by hand, or scaffolded before the #3209 rename, does
+ * not leave push reporting success over a program no compiler can load
+ * (SO3182-004). Everything else in the file is left exactly as written.
+ *
+ * None of the three is part of the pushed envelope: they are regenerated, not
+ * round-tripped, and the bundler never sees them (types are erased, and the
+ * tsconfig is not a module).
+ */
+export declare const DB_TYPES_DECLARATION_FILE = "primitive-db-types.d.ts";
+export declare const SDK_TYPES_FILE = "primitive-functions.d.ts";
+export declare const FUNCTIONS_TSCONFIG_FILE = "tsconfig.json";
+export interface DatabaseTypeSource {
+    databaseType: string;
+    tomlPath: string;
+    tomlContent: string;
+}
+/**
+ * The declaration for a whole config tree's database types.
+ *
+ * Sorted by type and by model so the bytes depend on the SCHEMAS and not on
+ * the order the files were read in — push rewrites this on every run, and
+ * unstable output would be a permanent diff in a developer's repository.
+ */
+export declare function renderDbTypesDeclaration(sources: readonly DatabaseTypeSource[]): string;
+/** The scaffolded compiler wiring. Written once; an author owns it after. */
+export declare function renderFunctionsTsconfig(): string;
+/** The bare specifier every function imports, and the tsconfig must resolve. */
+export declare const SDK_MODULE_SPECIFIER = "primitive-functions";
+/** What push found wrong with a `functions/tsconfig.json` it will not rewrite. */
+export interface TsconfigWiringReport {
+    /** The document push should write, or null to leave the file as it is. */
+    repaired: string | null;
+    /**
+     * Wiring push could not repair, phrased for the author to act on. Empty when
+     * the file is fine or was repaired.
+     */
+    problems: string[];
+}
+/**
+ * Whether an existing tsconfig still carries the wiring the handle needs — the
+ * repaired document when push can fix it, and the problems when it cannot.
+ *
+ * The scaffold is written once and then belongs to its author, but "belongs to
+ * its author" cannot mean "silently stops working": a tree scaffolded before
+ * the `primitive-functions` rename (#3209) points at a declaration push no
+ * longer writes, and a tsconfig an author wrote by hand never had the wiring at
+ * all. Either way push claims success while no compiler can load the
+ * augmentation (SO3182-004).
+ *
+ * So the three REQUIRED facts — the module path mapping, the declarations being
+ * in the program, and the SOURCES being in the program — are repaired in a
+ * plain-JSON file, and everything else in it is left exactly as written. The
+ * mapping is APPENDED to any the author already has, so a deliberate mapping
+ * still wins and ours is only the fallback.
+ *
+ * A JSONC file (comments are legal in a tsconfig) is never rewritten —
+ * reformatting an author's file is worse than leaving it — but it IS read, and
+ * anything missing is reported instead of passing in silence (CR3182-003).
+ */
+export declare function inspectFunctionsTsconfig(existing: string | null): TsconfigWiringReport;
+/**
+ * The repaired document alone, or null to leave the file alone.
+ *
+ * Kept as the narrow answer `planFunctionTypeArtifacts` needs; the problems a
+ * repair cannot cover travel through `inspectFunctionsTsconfig`.
+ */
+export declare function reconcileFunctionsTsconfig(existing: string | null): string | null;
+export interface FunctionTypeArtifact {
+    /** Tree-relative, POSIX. */
+    relative: string;
+    absolute: string;
+    contents: string;
+    /** Generated files are rewritten every push; the scaffold is written once. */
+    regenerated: boolean;
+}
+/**
+ * Every database-type TOML in the tree, read once.
+ *
+ * The type KEY is the one push and the grant preflight use — `[type]
+ * databaseType` when the file declares it, the file name only as the fallback.
+ * Taking the file name unconditionally would type the handle under a key the
+ * platform never hears about, so `ctx.db(id, "<declared-type>")` — the key the
+ * grant names — would not compile while a wrong one would (SO3182-003).
+ */
+export declare function databaseTypeSources(configDir: string): DatabaseTypeSource[];
+/**
+ * What push would write, without writing it.
+ *
+ * Nothing at all when the tree has no `functions/` directory: the artifacts
+ * exist to type function sources, and a tree with none needs no compiler
+ * wiring.
+ */
+export declare function planFunctionTypeArtifacts(configDir: string, sdkTypes?: string): FunctionTypeArtifact[];
+/**
+ * The tsconfig wiring push could not repair, phrased for the author.
+ *
+ * Push repairs a plain-JSON tsconfig in place, but it will not rewrite one that
+ * carries comments and it cannot read one that is broken. Reporting is what is
+ * left, and it is not optional: a typed handle that no compiler loads is the
+ * failure mode this whole artifact exists to prevent, and staying silent about
+ * it is how it reaches an author as "my types just don't work" (CR3182-003).
+ */
+export declare function functionTypeWiringProblems(configDir: string): string[];
+/** Write them, and report the tree-relative paths that changed on disk. */
+export declare function writeFunctionTypeArtifacts(configDir: string, sdkTypes?: string): string[];
+/**
+ * The artifacts a `--check` run would rewrite: the freshness answer for CI and
+ * for an editor that wants to know its types are current.
+ *
+ * The tsconfig is only ever planned when it is missing or its wiring is (see
+ * `reconcileFunctionsTsconfig`), so a hand-edited but correctly wired one is
+ * never reported — and one that would leave the declarations unloadable always
+ * is.
+ */
+export declare function staleFunctionTypeArtifacts(configDir: string): string[];