zitejs 0.9.102 → 0.9.104

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

@@ -16,6 +16,16 @@ export type ZiteSchema = {
 };
 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;
 /**
  * Build a ZiteSchema from a Database API response.
  *

package/dist/cjs/sync/lib.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toPascalCase = toPascalCase;
 exports.toCamelCase = toCamelCase;
+exports.toSdkName = toSdkName;
 exports.generateSchema = generateSchema;
 exports.generateDbTs = generateDbTs;
 exports.generateApiTs = generateApiTs;
@@ -13,48 +14,73 @@ const AUTH_USERS_TABLE_ID = "zite_user";
 /**
  * What a field's value looks like when a record is READ back.
  *
- * `| null` on the nullable ones is load-bearing, not pedantry: every field
- * column is created nullable with no default (`recordsTableManager`), and only
- * the six text types get their NULL rewritten to `''` on the way out
- * (`normalizeEmptyStringFields` keys on `emptyValue === ''`). The product's own
- * test asserts `fld_number` and `fld_checkbox` read back as `null`. Typing them
- * non-null let `task.estimate.toFixed(2)` compile and throw.
+ * **These are deliberately optimistic, and that is load-bearing.** Every column
+ * is nullable with no default (`recordsTableManager`) and only the six text
+ * types get NULL rewritten to `''`, so the wire really does answer `null` for
+ * the rest. They are typed `T | undefined` anyway, matching the pre-monorepo
+ * SDK — `| null` appears zero times in its generator.
+ *
+ * Two things have been tried and both broke apps, so before "fixing" this:
+ *
+ * 1. **Typing the truth** (`9a44ab3`). 7880 of 7880 audited 1.0 endpoints
+ *    declare an `outputSchema` written as a mirror of this type with every cell
+ *    `.optional()`, and `createEndpoint` constrains `execute`'s return against
+ *    it. `| null` fails the app's typecheck on lines nobody edited — 52 of 144
+ *    apps, ~2,100 sites.
+ * 2. **Making the runtime emit `undefined`** so the type becomes true. The
+ *    idiom that breaks is `.filter(m => m.homeScore !== null)`, which silently
+ *    becomes a no-op and lets empty rows through: wrong results, no error.
+ *    10 of 328 exported apps do exactly this.
+ *
+ * TODO: make these accurate in a deliberate zitejs major, once apps are
+ * migrated. Each app pins its own version, so the change only reaches apps that
+ * opt in by bumping — which is the only way to do it without breaking (2).
+ *
+ * Writes are unaffected — `null` is how you clear a cell. See
+ * `FIELD_INPUT_TYPE_MAP` and `withNull`.
  */
 const FIELD_TYPE_MAP = {
-    // Text: NULL is rewritten to '' on read, so these genuinely can't be null.
+    // Text: NULL is rewritten to '' on read, so these are never even absent.
     single_line_text: "string",
     long_text: "string",
     rich_text: "string",
     email: "string",
     url: "string",
     phone_number: "string",
-    number: "number | null",
-    currency: "number | null",
-    percent: "number | null",
-    rating: "number | null",
+    number: "number",
+    currency: "number",
+    percent: "number",
+    rating: "number",
     // DECIMAL seconds, unlike Airtable's, which is formatted to "HH:mm:ss".
-    duration: "number | null",
-    checkbox: "boolean | null",
-    single_select: "string | null",
-    multiple_select: "string[] | null",
-    date: "string | null",
-    datetime: "string | null",
-    attachments: "ZiteAttachment[] | null",
+    // 1.0 typed this `string`, which was simply wrong — base-runner groups it
+    // with the numeric types — so it stays a number rather than reverting.
+    duration: "number",
+    checkbox: "boolean",
+    single_select: "string",
+    multiple_select: "string[]",
+    date: "string",
+    datetime: "string",
+    attachments: "ZiteAttachment[]",
     // `string | string[]`, matching the pre-monorepo type. base-runner does force
     // an array on read today, but 1.0 code is written with `typeof x === 'string'`
     // guards — narrowing to `string[]` turns those branches into `never` and
     // fails the app's typecheck for no gain.
     linked_record: "string | string[]",
     user: "string | string[]",
-    lookup: "unknown",
-    rollup: "unknown",
+    // `any`, not `unknown`, and deliberately: these are values the platform
+    // cannot type — a lookup is whatever the far side holds. 1.0 said `any`, and
+    // `unknown` buys nothing because there is no narrowing an app could have
+    // written in advance: `sum + (x || 0)` is a TS2365 on `unknown`, and the
+    // guarded spellings already narrowed fine under `any`.
+    lookup: "any",
+    rollup: "any",
     autonumber: "number",
     // JSONB change metadata (`{ type: "PublicAPI", apiKeyId: 3 }`), not a string.
-    source: "unknown",
-    formula: "unknown",
+    source: "any",
+    formula: "any",
     created_at: "string",
     updated_at: "string",
-    updated_by: "string | null",
+    updated_by: "string",
 };
 /**
  * Field types whose WRITE shape differs from their read shape — the API accepts
@@ -170,6 +196,21 @@ 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.
+ */
+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
@@ -198,9 +239,9 @@ function tsTypeForSchemaField(def, variant = "read") {
                 .map((o) => `"${o.label.replace(/"/g, '\\"')}"`)
                 .join(" | ");
             const union = `${literals} | string`;
-            const read = def.type === "multiple_select"
-                ? `(${union})[] | null`
-                : `${union} | null`;
+            // No `| null` on the read side — see FIELD_TYPE_MAP. The write side keeps
+            // it below, since null is how a select cell is cleared.
+            const read = def.type === "multiple_select" ? `(${union})[]` : union;
             if (variant === "write") {
                 return def.type === "multiple_select"
                     ? `${union} | (${union})[] | null`
@@ -338,13 +379,13 @@ function generateSchema(database, existingSchema) {
             const { id: _id, order: _order, ...definition } = field;
             fields.push({
                 id: field.id,
-                sdkName: keepValidSdkName(existing?.sdkName) ?? toCamelCase(field.name),
+                sdkName: keepValidSdkName(existing?.sdkName) ?? toSdkName(field.name),
                 definition,
             });
         }
         tables.push({
             id: table.id,
-            sdkName: keepValidSdkName(existingTable?.sdkName) ?? toCamelCase(table.name),
+            sdkName: keepValidSdkName(existingTable?.sdkName) ?? toSdkName(table.name),
             primaryFieldId: table.primaryFieldId,
             fields,
         });

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

@@ -16,6 +16,16 @@ export type ZiteSchema = {
 };
 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;
 /**
  * Build a ZiteSchema from a Database API response.
  *

package/dist/esm/sync/lib.js

@@ -3,48 +3,73 @@ const AUTH_USERS_TABLE_ID = "zite_user";
 /**
  * What a field's value looks like when a record is READ back.
  *
- * `| null` on the nullable ones is load-bearing, not pedantry: every field
- * column is created nullable with no default (`recordsTableManager`), and only
- * the six text types get their NULL rewritten to `''` on the way out
- * (`normalizeEmptyStringFields` keys on `emptyValue === ''`). The product's own
- * test asserts `fld_number` and `fld_checkbox` read back as `null`. Typing them
- * non-null let `task.estimate.toFixed(2)` compile and throw.
+ * **These are deliberately optimistic, and that is load-bearing.** Every column
+ * is nullable with no default (`recordsTableManager`) and only the six text
+ * types get NULL rewritten to `''`, so the wire really does answer `null` for
+ * the rest. They are typed `T | undefined` anyway, matching the pre-monorepo
+ * SDK — `| null` appears zero times in its generator.
+ *
+ * Two things have been tried and both broke apps, so before "fixing" this:
+ *
+ * 1. **Typing the truth** (`9a44ab3`). 7880 of 7880 audited 1.0 endpoints
+ *    declare an `outputSchema` written as a mirror of this type with every cell
+ *    `.optional()`, and `createEndpoint` constrains `execute`'s return against
+ *    it. `| null` fails the app's typecheck on lines nobody edited — 52 of 144
+ *    apps, ~2,100 sites.
+ * 2. **Making the runtime emit `undefined`** so the type becomes true. The
+ *    idiom that breaks is `.filter(m => m.homeScore !== null)`, which silently
+ *    becomes a no-op and lets empty rows through: wrong results, no error.
+ *    10 of 328 exported apps do exactly this.
+ *
+ * TODO: make these accurate in a deliberate zitejs major, once apps are
+ * migrated. Each app pins its own version, so the change only reaches apps that
+ * opt in by bumping — which is the only way to do it without breaking (2).
+ *
+ * Writes are unaffected — `null` is how you clear a cell. See
+ * `FIELD_INPUT_TYPE_MAP` and `withNull`.
  */
 const FIELD_TYPE_MAP = {
-    // Text: NULL is rewritten to '' on read, so these genuinely can't be null.
+    // Text: NULL is rewritten to '' on read, so these are never even absent.
     single_line_text: "string",
     long_text: "string",
     rich_text: "string",
     email: "string",
     url: "string",
     phone_number: "string",
-    number: "number | null",
-    currency: "number | null",
-    percent: "number | null",
-    rating: "number | null",
+    number: "number",
+    currency: "number",
+    percent: "number",
+    rating: "number",
     // DECIMAL seconds, unlike Airtable's, which is formatted to "HH:mm:ss".
-    duration: "number | null",
-    checkbox: "boolean | null",
-    single_select: "string | null",
-    multiple_select: "string[] | null",
-    date: "string | null",
-    datetime: "string | null",
-    attachments: "ZiteAttachment[] | null",
+    // 1.0 typed this `string`, which was simply wrong — base-runner groups it
+    // with the numeric types — so it stays a number rather than reverting.
+    duration: "number",
+    checkbox: "boolean",
+    single_select: "string",
+    multiple_select: "string[]",
+    date: "string",
+    datetime: "string",
+    attachments: "ZiteAttachment[]",
     // `string | string[]`, matching the pre-monorepo type. base-runner does force
     // an array on read today, but 1.0 code is written with `typeof x === 'string'`
     // guards — narrowing to `string[]` turns those branches into `never` and
     // fails the app's typecheck for no gain.
     linked_record: "string | string[]",
     user: "string | string[]",
-    lookup: "unknown",
-    rollup: "unknown",
+    // `any`, not `unknown`, and deliberately: these are values the platform
+    // cannot type — a lookup is whatever the far side holds. 1.0 said `any`, and
+    // `unknown` buys nothing because there is no narrowing an app could have
+    // written in advance: `sum + (x || 0)` is a TS2365 on `unknown`, and the
+    // guarded spellings already narrowed fine under `any`.
+    lookup: "any",
+    rollup: "any",
     autonumber: "number",
     // JSONB change metadata (`{ type: "PublicAPI", apiKeyId: 3 }`), not a string.
-    source: "unknown",
-    formula: "unknown",
+    source: "any",
+    formula: "any",
     created_at: "string",
     updated_at: "string",
-    updated_by: "string | null",
+    updated_by: "string",
 };
 /**
  * Field types whose WRITE shape differs from their read shape — the API accepts
@@ -160,6 +185,21 @@ 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
@@ -188,9 +228,9 @@ function tsTypeForSchemaField(def, variant = "read") {
                 .map((o) => `"${o.label.replace(/"/g, '\\"')}"`)
                 .join(" | ");
             const union = `${literals} | string`;
-            const read = def.type === "multiple_select"
-                ? `(${union})[] | null`
-                : `${union} | null`;
+            // No `| null` on the read side — see FIELD_TYPE_MAP. The write side keeps
+            // it below, since null is how a select cell is cleared.
+            const read = def.type === "multiple_select" ? `(${union})[]` : union;
             if (variant === "write") {
                 return def.type === "multiple_select"
                     ? `${union} | (${union})[] | null`
@@ -328,13 +368,13 @@ export function generateSchema(database, existingSchema) {
             const { id: _id, order: _order, ...definition } = field;
             fields.push({
                 id: field.id,
-                sdkName: keepValidSdkName(existing?.sdkName) ?? toCamelCase(field.name),
+                sdkName: keepValidSdkName(existing?.sdkName) ?? toSdkName(field.name),
                 definition,
             });
         }
         tables.push({
             id: table.id,
-            sdkName: keepValidSdkName(existingTable?.sdkName) ?? toCamelCase(table.name),
+            sdkName: keepValidSdkName(existingTable?.sdkName) ?? toSdkName(table.name),
             primaryFieldId: table.primaryFieldId,
             fields,
         });

package/package.json

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