zitejs 0.9.105 → 0.9.106

package/dist/esm/sync/sdkNames.js

@@ -0,0 +1,269 @@
+/**
+ * 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.
+ */
+// The case helpers live here rather than in lib.ts so this module has no import
+// back into it — `lib.ts` needs the allocator, and a cycle between the two is
+// avoidable. `lib.ts` re-exports them, so the published surface is unchanged.
+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);
+}
+/**
+ * Accessors `generateDbTs` puts on the `zite` object itself, after the tables.
+ * A table that allocates one of these produces a duplicate key.
+ */
+export const RESERVED_TABLE_ACCESSORS = [
+    "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 const RESERVED_IDENTIFIERS = [
+    "__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 const RESERVED_FIELD_ACCESSORS = ["id"];
+/** Guards the suffix loop. Far above any real schema; see `allocate`. */
+const MAX_SUFFIX_ATTEMPTS = 10_000;
+/**
+ * Unique identifiers within one namespace.
+ *
+ * `derive` names the extra keys an allocation also occupies. A table needs it:
+ * its sdkName becomes both a property on `zite` and, PascalCased, a pair of
+ * exported type declarations, so `orders` and `Orders` are distinct accessors
+ * that would emit `OrdersRecordType` twice.
+ */
+class SdkNameAllocator {
+    taken = new Set();
+    reserved;
+    derive;
+    constructor(opts = {}) {
+        this.reserved = new Set([
+            ...RESERVED_IDENTIFIERS,
+            ...(opts.reserved ?? []),
+        ]);
+        this.derive = opts.derive ?? (() => []);
+    }
+    keysFor(name) {
+        return [name, ...this.derive(name)];
+    }
+    isFree(name) {
+        return this.keysFor(name).every((key) => !this.taken.has(key) && !this.reserved.has(key));
+    }
+    /** Free right now, without claiming it. */
+    available(name) {
+        return this.isFree(name);
+    }
+    claim(name) {
+        for (const key of this.keysFor(name))
+            this.taken.add(key);
+        return name;
+    }
+    /**
+     * `name`, or the first `name2`, `name3`… that is free. Suffixes start at 2
+     * because that is what the name means: the second table called Notifications.
+     */
+    allocate(preferred) {
+        const base = preferred || "_";
+        if (this.isFree(base))
+            return this.claim(base);
+        for (let suffix = 2; suffix <= MAX_SUFFIX_ATTEMPTS; suffix++) {
+            const candidate = `${base}${suffix}`;
+            if (this.isFree(candidate))
+                return this.claim(candidate);
+        }
+        // Unreachable: each attempt blocks at most two keys, so a free candidate
+        // exists long before the cap. A generator must never return a duplicate,
+        // so say so rather than emitting one.
+        throw new Error(`Could not allocate a unique SDK name for "${preferred}" after ${MAX_SUFFIX_ATTEMPTS} attempts`);
+    }
+}
+/**
+ * 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 function keepValidSdkName(sdkName) {
+    if (!sdkName)
+        return undefined;
+    return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(sdkName) ? sdkName : undefined;
+}
+/**
+ * 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 function allocateSchemaNames(drafts) {
+    const renames = [];
+    const tableNames = new SdkNameAllocator({
+        reserved: RESERVED_TABLE_ACCESSORS,
+        // The PascalCase form is its own pair of exported declarations.
+        derive: (name) => [`type:${toPascalCase(name)}`],
+    });
+    const resolved = new Map();
+    for (const pass of [true, false]) {
+        for (const entry of drafts) {
+            if (entry.draft.locked !== pass)
+                continue;
+            if (pass && !tableNames.available(entry.draft.preferred))
+                continue;
+            const sdkName = tableNames.allocate(entry.draft.preferred);
+            resolved.set(entry.table.id, sdkName);
+            if (sdkName !== entry.draft.preferred) {
+                renames.push({
+                    kind: "table",
+                    tableId: entry.table.id,
+                    from: entry.draft.preferred,
+                    to: sdkName,
+                });
+            }
+        }
+    }
+    // A locked name skipped in pass 1 (reserved, or claimed by an earlier locked
+    // name) falls through to here and is suffixed like any other.
+    for (const entry of drafts) {
+        if (resolved.has(entry.table.id))
+            continue;
+        const sdkName = tableNames.allocate(entry.draft.preferred);
+        resolved.set(entry.table.id, sdkName);
+        renames.push({
+            kind: "table",
+            tableId: entry.table.id,
+            from: entry.draft.preferred,
+            to: sdkName,
+        });
+    }
+    const tables = drafts.map((entry) => {
+        const fieldNames = new SdkNameAllocator({
+            reserved: RESERVED_FIELD_ACCESSORS,
+        });
+        const resolvedFields = new Map();
+        for (const pass of [true, false]) {
+            for (const { field, draft } of entry.fields) {
+                if (draft.locked !== pass)
+                    continue;
+                if (pass && !fieldNames.available(draft.preferred))
+                    continue;
+                const sdkName = fieldNames.allocate(draft.preferred);
+                resolvedFields.set(field.id, sdkName);
+                if (sdkName !== draft.preferred) {
+                    renames.push({
+                        kind: "field",
+                        tableId: entry.table.id,
+                        fieldId: field.id,
+                        from: draft.preferred,
+                        to: sdkName,
+                    });
+                }
+            }
+        }
+        for (const { field, draft } of entry.fields) {
+            if (resolvedFields.has(field.id))
+                continue;
+            const sdkName = fieldNames.allocate(draft.preferred);
+            resolvedFields.set(field.id, sdkName);
+            renames.push({
+                kind: "field",
+                tableId: entry.table.id,
+                fieldId: field.id,
+                from: draft.preferred,
+                to: sdkName,
+            });
+        }
+        return {
+            ...entry.table,
+            sdkName: resolved.get(entry.table.id),
+            fields: entry.fields.map(({ field }) => ({
+                ...field,
+                sdkName: resolvedFields.get(field.id),
+            })),
+        };
+    });
+    return { tables, renames };
+}
+/**
+ * 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 function normalizeSchemaNames(schema) {
+    const { tables, renames } = allocateSchemaNames(schema.tables.map((table) => ({
+        table,
+        draft: {
+            preferred: keepValidSdkName(table.sdkName) ?? toSdkName(table.sdkName),
+            locked: true,
+        },
+        fields: table.fields.map((field) => ({
+            field,
+            draft: {
+                preferred: keepValidSdkName(field.sdkName) ?? toSdkName(field.sdkName),
+                locked: true,
+            },
+        })),
+    })));
+    return { schema: { tables }, renames };
+}
+/** One line per rename, for a generator that has no logger of its own. */
+export function describeRenames(renames) {
+    return renames.map((r) => r.kind === "table"
+        ? `table "${r.from}" -> "${r.to}" (id ${r.tableId})`
+        : `field "${r.from}" -> "${r.to}" (table ${r.tableId}, field ${r.fieldId})`);
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,203 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { generateSchema, generateDbTs } from "./lib.js";
+import { normalizeSchemaNames } from "./sdkNames.js";
+// `generateSchema` warns on every rename; silence it so the suite stays
+// readable, and assert on the emitted names instead.
+beforeEach(() => {
+    vi.spyOn(console, "warn").mockImplementation(() => { });
+});
+afterEach(() => {
+    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]);
+};
+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) }`.
+    it("moves a table off the notifications accessor", () => {
+        const schema = generateSchema(database([{ id: "tbl_1", name: "Notifications", fields: [] }]));
+        expect(schema.tables[0].sdkName).toBe("notifications2");
+        const keys = ziteKeys(generateDbTs(schema));
+        expect(keys).toContain("notifications2");
+        expect(keys.filter((k) => k === "notifications")).toHaveLength(1);
+        expect(new Set(keys).size).toBe(keys.length);
+    });
+    it.each(["sql", "auth", "notifications"])("keeps the platform %s accessor for the platform", (reserved) => {
+        const schema = generateSchema(database([{ id: "tbl_1", name: reserved, fields: [] }]));
+        expect(schema.tables[0].sdkName).toBe(`${reserved}2`);
+        const keys = ziteKeys(generateDbTs(schema));
+        expect(new Set(keys).size).toBe(keys.length);
+    });
+    it.each(["__proto__", "constructor", "prototype"])("refuses %s as a table accessor", (hazard) => {
+        const schema = generateSchema(database([{ id: "tbl_1", name: hazard, fields: [] }]));
+        expect(schema.tables[0].sdkName).not.toBe(hazard);
+    });
+});
+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.
+    it("keeps both fields when two display names normalize alike", () => {
+        const schema = 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);
+        expect(names).toEqual(["category", "category2"]);
+        const keys = recordTypeKeys(generateDbTs(schema), "K9WinnersRecordType");
+        expect(keys).toEqual(["id", "category", "category2"]);
+    });
+    it("de-duplicates two tables that normalize alike", () => {
+        const schema = generateSchema(database([
+            { id: "tbl_1", name: "Orders", fields: [] },
+            { id: "tbl_2", name: "orders", fields: [] },
+        ]));
+        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.
+    it("separates tables whose class names would collide", () => {
+        const source = 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]);
+        expect(new Set(declared).size).toBe(declared.length);
+    });
+    it("reserves id so a field named ID stays readable", () => {
+        const schema = generateSchema(database([{ id: "tbl_1", name: "Rows", fields: [field("fld_1", "ID")] }]));
+        expect(schema.tables[0].fields[0].sdkName).toBe("id2");
+        expect(recordTypeKeys(generateDbTs(schema), "RowsRecordType")).toEqual([
+            "id",
+            "id2",
+        ]);
+    });
+});
+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.
+    it("preserves a locked name over the one the display name would produce", () => {
+        const schema = generateSchema(database([
+            {
+                id: "tbl_1",
+                name: "Price List",
+                fields: [field("fld_1", "SRP (Suggested Retail Price)")],
+            },
+        ]), existing);
+        expect(schema.tables[0].fields[0].sdkName).toBe("srp");
+    });
+    it("does not let a new field displace a locked one", () => {
+        const schema = 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]));
+        expect(byId.fld_1).toBe("srp");
+        expect(byId.fld_2).toBe("srp2");
+    });
+    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 = generateSchema(db);
+        const second = generateSchema(db, first);
+        const third = generateSchema(db, second);
+        expect(second).toEqual(first);
+        expect(third).toEqual(first);
+    });
+    it("recomputes a name that is not a valid identifier", () => {
+        const schema = 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" },
+                        },
+                    ],
+                },
+            ],
+        });
+        expect(schema.tables[0].fields[0].sdkName).toBe("time");
+    });
+});
+describe("normalizeSchemaNames", () => {
+    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 = normalizeSchemaNames(schema);
+        expect(result.renames).toEqual([]);
+        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.
+    it("repairs a committed schema that already holds the collision", () => {
+        const source = generateDbTs({
+            tables: [
+                { id: "tbl_1", sdkName: "notifications", fields: [] },
+                { id: "tbl_2", sdkName: "orders", fields: [] },
+            ],
+        });
+        const keys = ziteKeys(source);
+        expect(new Set(keys).size).toBe(keys.length);
+        expect(keys).toContain("notifications2");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zitejs",
-  "version": "0.9.105",
+  "version": "0.9.106",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "main": "./dist/cjs/index.js",