zitejs 0.9.105 → 0.9.106

package/dist/cjs/sync/sdkNames.test.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const lib_js_1 = require("./lib.js");
+const sdkNames_js_1 = require("./sdkNames.js");
+// `generateSchema` warns on every rename; silence it so the suite stays
+// readable, and assert on the emitted names instead.
+(0, vitest_1.beforeEach)(() => {
+    vitest_1.vi.spyOn(console, "warn").mockImplementation(() => { });
+});
+(0, vitest_1.afterEach)(() => {
+    vitest_1.vi.restoreAllMocks();
+});
+const field = (id, name) => ({ id, name, type: "single_line_text", order: 0 });
+const database = (tables) => ({
+    id: "base_1",
+    name: "Base",
+    tables,
+    createdAt: "",
+    updatedAt: "",
+    url: "",
+});
+/** Every key in the emitted `export const zite = { … }` literal. */
+const ziteKeys = (source) => {
+    const body = source.slice(source.indexOf("export const zite = {"));
+    return [...body.matchAll(/^ {2}([A-Za-z_$][\w$]*):/gm)].map((m) => m[1]);
+};
+/** Every property key on one emitted record type. */
+const recordTypeKeys = (source, typeName) => {
+    const start = source.indexOf(`export type ${typeName} = {`);
+    const body = source.slice(start, source.indexOf("};", start));
+    return [...body.matchAll(/^ {2}([A-Za-z_$][\w$]*)\??:/gm)].map((m) => m[1]);
+};
+(0, vitest_1.describe)("reserved platform accessors", () => {
+    // Sudzy Dashboard: a table named "Notifications" emitted a second
+    // `notifications:` key, and the platform client — written last — won. The
+    // table lost findAll and typed as `{ create(NotificationsCreateParams) }`.
+    (0, vitest_1.it)("moves a table off the notifications accessor", () => {
+        const schema = (0, lib_js_1.generateSchema)(database([{ id: "tbl_1", name: "Notifications", fields: [] }]));
+        (0, vitest_1.expect)(schema.tables[0].sdkName).toBe("notifications2");
+        const keys = ziteKeys((0, lib_js_1.generateDbTs)(schema));
+        (0, vitest_1.expect)(keys).toContain("notifications2");
+        (0, vitest_1.expect)(keys.filter((k) => k === "notifications")).toHaveLength(1);
+        (0, vitest_1.expect)(new Set(keys).size).toBe(keys.length);
+    });
+    vitest_1.it.each(["sql", "auth", "notifications"])("keeps the platform %s accessor for the platform", (reserved) => {
+        const schema = (0, lib_js_1.generateSchema)(database([{ id: "tbl_1", name: reserved, fields: [] }]));
+        (0, vitest_1.expect)(schema.tables[0].sdkName).toBe(`${reserved}2`);
+        const keys = ziteKeys((0, lib_js_1.generateDbTs)(schema));
+        (0, vitest_1.expect)(new Set(keys).size).toBe(keys.length);
+    });
+    vitest_1.it.each(["__proto__", "constructor", "prototype"])("refuses %s as a table accessor", (hazard) => {
+        const schema = (0, lib_js_1.generateSchema)(database([{ id: "tbl_1", name: hazard, fields: [] }]));
+        (0, vitest_1.expect)(schema.tables[0].sdkName).not.toBe(hazard);
+    });
+});
+(0, vitest_1.describe)("collision de-duplication", () => {
+    // Nevada Car Coalition: 1.0's generator suffixed colliding names, so the app
+    // was written against `category1` / `sponsor1`. 2.0 had no accumulator at
+    // all, so the second field silently overwrote the first.
+    (0, vitest_1.it)("keeps both fields when two display names normalize alike", () => {
+        const schema = (0, lib_js_1.generateSchema)(database([
+            {
+                id: "tbl_1",
+                name: "K9 Winners",
+                fields: [field("fld_1", "Category"), field("fld_2", "category")],
+            },
+        ]));
+        const names = schema.tables[0].fields.map((f) => f.sdkName);
+        (0, vitest_1.expect)(names).toEqual(["category", "category2"]);
+        const keys = recordTypeKeys((0, lib_js_1.generateDbTs)(schema), "K9WinnersRecordType");
+        (0, vitest_1.expect)(keys).toEqual(["id", "category", "category2"]);
+    });
+    (0, vitest_1.it)("de-duplicates two tables that normalize alike", () => {
+        const schema = (0, lib_js_1.generateSchema)(database([
+            { id: "tbl_1", name: "Orders", fields: [] },
+            { id: "tbl_2", name: "orders", fields: [] },
+        ]));
+        (0, vitest_1.expect)(schema.tables.map((t) => t.sdkName)).toEqual(["orders", "orders2"]);
+    });
+    // Two sdkNames sharing a PascalCase form emit `FooRecordType` twice, which is
+    // a duplicate identifier even though the accessors differ.
+    (0, vitest_1.it)("separates tables whose class names would collide", () => {
+        const source = (0, lib_js_1.generateDbTs)({
+            tables: [
+                { id: "tbl_1", sdkName: "orders", fields: [] },
+                { id: "tbl_2", sdkName: "Orders", fields: [] },
+            ],
+        });
+        const declared = [...source.matchAll(/export type (\w+RecordType)/g)].map((m) => m[1]);
+        (0, vitest_1.expect)(new Set(declared).size).toBe(declared.length);
+    });
+    (0, vitest_1.it)("reserves id so a field named ID stays readable", () => {
+        const schema = (0, lib_js_1.generateSchema)(database([{ id: "tbl_1", name: "Rows", fields: [field("fld_1", "ID")] }]));
+        (0, vitest_1.expect)(schema.tables[0].fields[0].sdkName).toBe("id2");
+        (0, vitest_1.expect)(recordTypeKeys((0, lib_js_1.generateDbTs)(schema), "RowsRecordType")).toEqual([
+            "id",
+            "id2",
+        ]);
+    });
+});
+(0, vitest_1.describe)("name stability", () => {
+    const existing = {
+        tables: [
+            {
+                id: "tbl_1",
+                sdkName: "priceList",
+                fields: [
+                    { id: "fld_1", sdkName: "srp", definition: { type: "number" } },
+                ],
+            },
+        ],
+    };
+    // Kelly: the app was written against `srp`, and the field's display name has
+    // drifted since. A locked name is what the app compiles against.
+    (0, vitest_1.it)("preserves a locked name over the one the display name would produce", () => {
+        const schema = (0, lib_js_1.generateSchema)(database([
+            {
+                id: "tbl_1",
+                name: "Price List",
+                fields: [field("fld_1", "SRP (Suggested Retail Price)")],
+            },
+        ]), existing);
+        (0, vitest_1.expect)(schema.tables[0].fields[0].sdkName).toBe("srp");
+    });
+    (0, vitest_1.it)("does not let a new field displace a locked one", () => {
+        const schema = (0, lib_js_1.generateSchema)(database([
+            {
+                id: "tbl_1",
+                name: "Price List",
+                // The new field's fresh name is exactly what fld_1 holds.
+                fields: [field("fld_2", "SRP"), field("fld_1", "Anything")],
+            },
+        ]), existing);
+        const byId = Object.fromEntries(schema.tables[0].fields.map((f) => [f.id, f.sdkName]));
+        (0, vitest_1.expect)(byId.fld_1).toBe("srp");
+        (0, vitest_1.expect)(byId.fld_2).toBe("srp2");
+    });
+    (0, vitest_1.it)("is stable across repeated generation", () => {
+        const db = database([
+            {
+                id: "tbl_1",
+                name: "Notifications",
+                fields: [field("fld_1", "Category"), field("fld_2", "category")],
+            },
+        ]);
+        const first = (0, lib_js_1.generateSchema)(db);
+        const second = (0, lib_js_1.generateSchema)(db, first);
+        const third = (0, lib_js_1.generateSchema)(db, second);
+        (0, vitest_1.expect)(second).toEqual(first);
+        (0, vitest_1.expect)(third).toEqual(first);
+    });
+    (0, vitest_1.it)("recomputes a name that is not a valid identifier", () => {
+        const schema = (0, lib_js_1.generateSchema)(database([
+            { id: "tbl_1", name: "Rows", fields: [field("fld_1", "Time")] },
+        ]), {
+            tables: [
+                {
+                    id: "tbl_1",
+                    sdkName: "rows",
+                    fields: [
+                        {
+                            id: "fld_1",
+                            sdkName: "timeSeconds)",
+                            definition: { type: "number" },
+                        },
+                    ],
+                },
+            ],
+        });
+        (0, vitest_1.expect)(schema.tables[0].fields[0].sdkName).toBe("time");
+    });
+});
+(0, vitest_1.describe)("normalizeSchemaNames", () => {
+    (0, vitest_1.it)("is a no-op on a well-formed schema", () => {
+        const schema = {
+            tables: [
+                {
+                    id: "tbl_1",
+                    sdkName: "orders",
+                    fields: [
+                        { id: "fld_1", sdkName: "total", definition: { type: "number" } },
+                    ],
+                },
+            ],
+        };
+        const result = (0, sdkNames_js_1.normalizeSchemaNames)(schema);
+        (0, vitest_1.expect)(result.renames).toEqual([]);
+        (0, vitest_1.expect)(result.schema).toEqual(schema);
+    });
+    // A schema committed before allocation existed. The sandbox's boot-time
+    // `zitejs generate` reads it with no generateSchema pass in front, so this is
+    // the only thing standing between it and a TS1117 it cannot build past.
+    (0, vitest_1.it)("repairs a committed schema that already holds the collision", () => {
+        const source = (0, lib_js_1.generateDbTs)({
+            tables: [
+                { id: "tbl_1", sdkName: "notifications", fields: [] },
+                { id: "tbl_2", sdkName: "orders", fields: [] },
+            ],
+        });
+        const keys = ziteKeys(source);
+        (0, vitest_1.expect)(new Set(keys).size).toBe(keys.length);
+        (0, vitest_1.expect)(keys).toContain("notifications2");
+    });
+});

package/dist/esm/api/index.d.ts

@@ -0,0 +1,2 @@
+export { createCaller } from '../caller/index.js';
+export type { EndpointConfig } from '../caller/index.js';

package/dist/esm/api/index.js

@@ -0,0 +1 @@
+export { createCaller } from '../caller/index.js';

package/dist/esm/db/index.d.ts

@@ -0,0 +1,2 @@
+export { createTableClient } from '../runtime/index.js';
+export type { TableClient } from '../runtime/index.js';

package/dist/esm/db/index.js

@@ -0,0 +1 @@
+export { createTableClient } from '../runtime/index.js';

package/dist/esm/sync/lib.d.ts

@@ -14,18 +14,7 @@ export type ZiteSchemaTable = {
 export type ZiteSchema = {
     tables: ZiteSchemaTable[];
 };
-export declare function toPascalCase(name: string): string;
-export declare function toCamelCase(name: string): string;
-/**
- * camelCase for a FRESH sdkName, reading acronym runs as words: "VIP" ->
- * "vip", "APIKey" -> "apiKey" (plain toCamelCase yields "vIP" / "aPIKey").
- *
- * Deliberately not folded into toCamelCase: that also derives endpoint
- * identifiers from existing filenames on every generate, where normalizing
- * would rename a working app's `api.sendSMS`. This is only for names being
- * chosen for the first time — generateSchema preserves existing sdkNames.
- */
-export declare function toSdkName(name: string): string;
+export { toPascalCase, toCamelCase, toSdkName } from "./sdkNames.js";
 /**
  * Build a ZiteSchema from a Database API response.
  *
@@ -39,7 +28,7 @@ export declare function generateSchema(database: Database, existingSchema?: Zite
  * Generate .zite/db.ts purely from ZiteSchema.
  * Pure function — no external data needed beyond what's in the schema file.
  */
-export declare function generateDbTs(schema: ZiteSchema): string;
+export declare function generateDbTs(inputSchema: ZiteSchema): string;
 export type EndpointFileInfo = {
     fileName: string;
     content?: string;

package/dist/esm/sync/lib.js

@@ -1,4 +1,5 @@
 import { parse } from "@babel/parser";
+import { allocateSchemaNames, describeRenames, keepValidSdkName, normalizeSchemaNames, toCamelCase, toPascalCase, toSdkName, } from "./sdkNames.js";
 const AUTH_USERS_TABLE_ID = "zite_user";
 /**
  * What a field's value looks like when a record is READ back.
@@ -170,47 +171,9 @@ const withDateFormatExample = (format) => {
         ? `"${format}" format (e.g. ${example})`
         : `"${format}" format`;
 };
-export function toPascalCase(name) {
-    const pascal = name
-        .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
-        .replace(/^(.)/, (_, c) => c.toUpperCase())
-        // Drop leftover non-alphanumerics (e.g. a trailing ">" from "</p>") so the
-        // sdkName is always a valid identifier in .zite/db.ts.
-        .replace(/[^a-zA-Z0-9]+/g, "");
-    if (!pascal)
-        return "_";
-    return /^[0-9]/.test(pascal) ? `_${pascal}` : pascal; // can't start with a digit
-}
-export function toCamelCase(name) {
-    const pascal = toPascalCase(name);
-    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
-}
-/**
- * camelCase for a FRESH sdkName, reading acronym runs as words: "VIP" ->
- * "vip", "APIKey" -> "apiKey" (plain toCamelCase yields "vIP" / "aPIKey").
- *
- * Deliberately not folded into toCamelCase: that also derives endpoint
- * identifiers from existing filenames on every generate, where normalizing
- * would rename a working app's `api.sendSMS`. This is only for names being
- * chosen for the first time — generateSchema preserves existing sdkNames.
- */
-export function toSdkName(name) {
-    const deAcronymed = name
-        .replace(/([A-Z]+)([A-Z][a-z])/g, (_, run, next) => run.charAt(0) + run.slice(1).toLowerCase() + next)
-        .replace(/([A-Z])([A-Z]+)/g, (_, first, rest) => first + rest.toLowerCase());
-    return toCamelCase(deAcronymed);
-}
-/**
- * Existing sdkNames are preserved across syncs so user code keeps compiling,
- * but schemas written before the sanitizer stripped trailing symbols can carry
- * invalid identifiers (e.g. "timeSeconds)"). Keep an existing name only when
- * it's a valid identifier; otherwise fall through to recomputing it.
- */
-function keepValidSdkName(sdkName) {
-    if (!sdkName)
-        return undefined;
-    return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(sdkName) ? sdkName : undefined;
-}
+// Owned by ./sdkNames.ts (which must not import back into this module);
+// re-exported so the published surface is unchanged.
+export { toPascalCase, toCamelCase, toSdkName } from "./sdkNames.js";
 /**
  * `null` is how you CLEAR a cell — every scalar write schema in
  * `flexible-inputs.ts` ends in `.nullable()` and update runs with
@@ -353,7 +316,7 @@ export function generateSchema(database, existingSchema) {
     for (const t of existingSchema?.tables ?? []) {
         existingTableById.set(t.id, t);
     }
-    const tables = [];
+    const drafts = [];
     for (const table of database.tables) {
         if (table.id === AUTH_USERS_TABLE_ID)
             continue;
@@ -362,23 +325,44 @@ export function generateSchema(database, existingSchema) {
         for (const f of existingTable?.fields ?? []) {
             existingFieldById.set(f.id, f);
         }
-        const fields = [];
-        for (const field of table.fields) {
-            const existing = existingFieldById.get(field.id);
+        // `sdkName` is filled in by `allocateSchemaNames` below; the draft carries
+        // what each name would like to be and whether user code already depends on
+        // it. A name from the existing schema is locked — it is what the app is
+        // compiling against — and only moves if it is reserved or collides.
+        const fields = table.fields.map((field) => {
+            const existing = keepValidSdkName(existingFieldById.get(field.id)?.sdkName);
             const { id: _id, order: _order, ...definition } = field;
-            fields.push({
-                id: field.id,
-                sdkName: keepValidSdkName(existing?.sdkName) ?? toSdkName(field.name),
-                definition,
-            });
-        }
-        tables.push({
-            id: table.id,
-            sdkName: keepValidSdkName(existingTable?.sdkName) ?? toSdkName(table.name),
-            primaryFieldId: table.primaryFieldId,
+            return {
+                field: { id: field.id, sdkName: "", definition },
+                draft: {
+                    preferred: existing ?? toSdkName(field.name),
+                    locked: existing !== undefined,
+                },
+            };
+        });
+        const existingName = keepValidSdkName(existingTable?.sdkName);
+        drafts.push({
+            table: {
+                id: table.id,
+                sdkName: "",
+                primaryFieldId: table.primaryFieldId,
+                fields: [],
+            },
+            draft: {
+                preferred: existingName ?? toSdkName(table.name),
+                locked: existingName !== undefined,
+            },
             fields,
         });
     }
+    const { tables, renames } = allocateSchemaNames(drafts);
+    if (renames.length > 0) {
+        // Never silent: a rename means the accessor a developer would reach for is
+        // not the one that got emitted.
+        for (const line of describeRenames(renames)) {
+            console.warn(`[zitejs] SDK name collision resolved: ${line}`);
+        }
+    }
     return { tables };
 }
 function generateSentinelSdkTypes() {
@@ -466,8 +450,20 @@ function buildLinkTableComments(schema) {
  * Generate .zite/db.ts purely from ZiteSchema.
  * Pure function — no external data needed beyond what's in the schema file.
  */
-export function generateDbTs(schema) {
+export function generateDbTs(inputSchema) {
     const lines = [];
+    // Defensive, and idempotent: a schema whose names are already unique and
+    // unreserved normalizes to itself. It matters for a `zite.schema.json`
+    // committed before allocation existed — the sandbox's boot-time
+    // `zitejs generate` reads that file directly, with no `generateSchema` pass
+    // in front of it, and would otherwise emit an object literal with a
+    // duplicate key (TS1117) that no build can recover from.
+    const { schema, renames } = normalizeSchemaNames(inputSchema);
+    if (renames.length > 0) {
+        for (const line of describeRenames(renames)) {
+            console.warn(`[zitejs] Repaired SDK name in zite.schema.json: ${line}`);
+        }
+    }
     const tables = schema.tables.filter((table) => table.id !== AUTH_USERS_TABLE_ID);
     lines.push("// Auto-generated by zitejs generate. Do not edit manually.");
     lines.push("//");

package/dist/esm/sync/sdkNames.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Allocation of the identifiers `generateDbTs` emits.
+ *
+ * Every accessor on the generated `zite` object, and every field key on a
+ * record type, has to be unique — and `generateSchema` used to choose them with
+ * `toSdkName` and no memory at all. Two consequences, both seen in the wild:
+ *
+ *   - A table named "Notifications" allocated `notifications`, which
+ *     `generateDbTs` also emits for the platform's notifications client. The
+ *     sentinel is written last, so it won: the table lost its client entirely
+ *     and typed as `{ create(params: NotificationsCreateParams) }`.
+ *   - Two fields whose display names normalize alike both claimed one accessor,
+ *     and the second silently overwrote the first in the emitted type. No
+ *     error, no diagnostic — just a column you could no longer read. Zite 1.0's
+ *     generator de-duplicated with numeric suffixes; 2.0 dropped that.
+ *
+ * `allocateSchemaNames` is idempotent: a schema whose names are already unique
+ * and unreserved allocates to itself. That is what lets `generateDbTs` run it
+ * defensively over its input — a schema file written before this existed
+ * repairs itself on the next generate instead of emitting TypeScript that
+ * cannot compile.
+ */
+import type { ZiteSchema, ZiteSchemaField, ZiteSchemaTable } from "./lib.js";
+export declare function toPascalCase(name: string): string;
+export declare function toCamelCase(name: string): string;
+/**
+ * camelCase for a FRESH sdkName, reading acronym runs as words: "VIP" ->
+ * "vip", "APIKey" -> "apiKey" (plain toCamelCase yields "vIP" / "aPIKey").
+ *
+ * Deliberately not folded into toCamelCase: that also derives endpoint
+ * identifiers from existing filenames on every generate, where normalizing
+ * would rename a working app's `api.sendSMS`. This is only for names being
+ * chosen for the first time — generateSchema preserves existing sdkNames.
+ */
+export declare function toSdkName(name: string): string;
+/**
+ * Accessors `generateDbTs` puts on the `zite` object itself, after the tables.
+ * A table that allocates one of these produces a duplicate key.
+ */
+export declare const RESERVED_TABLE_ACCESSORS: readonly ["sql", "notifications", "auth"];
+/**
+ * Never safe as a generated key, in any namespace. Assigning `__proto__` in an
+ * object literal sets the prototype rather than defining a property, and
+ * `constructor` / `prototype` shadow members every object already carries.
+ */
+export declare const RESERVED_IDENTIFIERS: readonly ["__proto__", "constructor", "prototype"];
+/**
+ * `id` is emitted by hand on every record type and filtered out of every input
+ * type, so a field that allocated it vanished from both. Reserving it means a
+ * field genuinely named "ID" gets a usable accessor instead.
+ */
+export declare const RESERVED_FIELD_ACCESSORS: readonly ["id"];
+/** A name that could not be kept, reported so a rename is never silent. */
+export interface SdkNameRename {
+    kind: "table" | "field";
+    /** The table this happened in; the table itself for `kind: 'table'`. */
+    tableId: string;
+    fieldId?: string;
+    from: string;
+    to: string;
+}
+/**
+ * Existing sdkNames are preserved across syncs so user code keeps compiling,
+ * but a schema written before the sanitizer stripped trailing symbols can carry
+ * an invalid identifier (e.g. `timeSeconds)`). Keep one only when it is a valid
+ * identifier; otherwise the caller recomputes it from the display name.
+ */
+export declare function keepValidSdkName(sdkName: string | undefined): string | undefined;
+/** What a table/field would like to be called, and how hard it is holding on. */
+interface NameDraft {
+    preferred: string;
+    /**
+     * True when the name is already baked into a committed schema and user code
+     * is compiling against it. Locked names are claimed first, so a fresh name
+     * can never displace one; a locked name still moves when it is reserved or
+     * when two locked names collide, because the alternative is a file that does
+     * not compile.
+     */
+    locked: boolean;
+}
+export interface SchemaNameDraft {
+    table: ZiteSchemaTable;
+    draft: NameDraft;
+    fields: Array<{
+        field: ZiteSchemaField;
+        draft: NameDraft;
+    }>;
+}
+/**
+ * Resolve every drafted name to a unique, unreserved one.
+ *
+ * Two passes per namespace: locked names claim first in declaration order, then
+ * fresh ones fill in around them. Without that ordering a new table could take
+ * an accessor an existing app already imports.
+ */
+export declare function allocateSchemaNames(drafts: SchemaNameDraft[]): {
+    tables: ZiteSchemaTable[];
+    renames: SdkNameRename[];
+};
+/**
+ * Repair a schema whose names may already be unique — the idempotent case — or
+ * may predate allocation entirely. Everything is treated as locked: these names
+ * are what user code compiles against, so only a genuine conflict moves one.
+ */
+export declare function normalizeSchemaNames(schema: ZiteSchema): {
+    schema: ZiteSchema;
+    renames: SdkNameRename[];
+};
+/** One line per rename, for a generator that has no logger of its own. */
+export declare function describeRenames(renames: SdkNameRename[]): string[];
+export {};