zitejs 0.9.99 → 0.9.100

package/dist/cjs/sync/lib.js

@@ -10,33 +10,47 @@ exports.generateBackendWrapperTs = generateBackendWrapperTs;
 exports.generateEmailSdk = generateEmailSdk;
 const parser_1 = require("@babel/parser");
 const AUTH_USERS_TABLE_ID = "zite_user";
-/** What a field's value looks like when a record is READ back. */
+/**
+ * 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.
+ */
 const FIELD_TYPE_MAP = {
+    // Text: NULL is rewritten to '' on read, so these genuinely can't be null.
     single_line_text: "string",
     long_text: "string",
     rich_text: "string",
     email: "string",
     url: "string",
     phone_number: "string",
-    number: "number",
-    currency: "number",
-    percent: "number",
-    rating: "number",
-    duration: "number",
-    single_select: "string",
-    multiple_select: "string[]",
-    checkbox: "boolean",
+    number: "number | null",
+    currency: "number | null",
+    percent: "number | null",
+    rating: "number | null",
+    // 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[]",
-    // base-runner normalizes both of these to an array on write and stores them
-    // that way, so a read never produces a bare string.
-    linked_record: "string[]",
-    user: "string[]",
+    attachments: "ZiteAttachment[] | null",
+    // `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",
     autonumber: "number",
-    source: "string",
+    // JSONB change metadata (`{ type: "PublicAPI", apiKeyId: 3 }`), not a string.
+    source: "unknown",
     formula: "unknown",
     created_at: "string",
     updated_at: "string",
@@ -47,9 +61,18 @@ const FIELD_TYPE_MAP = {
  * looser input than it stores.
  */
 const FIELD_INPUT_TYPE_MAP = {
-    attachments: "ZiteAttachmentInput[]",
-    linked_record: "string | string[] | null",
-    user: "string | string[] | null",
+    attachments: "ZiteAttachmentInput[] | ZiteAttachmentInput",
+    linked_record: "string | string[]",
+    user: "string | string[]",
+    multiple_select: "string | string[]",
+    date: "string | Date",
+    datetime: "string | Date",
+    number: "string | number",
+    currency: "string | number",
+    percent: "string | number",
+    rating: "string | number",
+    duration: "string | number",
+    checkbox: "string | boolean",
 };
 /**
  * Computed and system-managed fields, omitted from the generated input type
@@ -156,6 +179,13 @@ function keepValidSdkName(sdkName) {
         return undefined;
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(sdkName) ? sdkName : undefined;
 }
+/**
+ * `null` is how you CLEAR a cell — every scalar write schema in
+ * `flexible-inputs.ts` ends in `.nullable()` and update runs with
+ * `allowExplicitNull`. A write type without it makes the documented way to
+ * empty a field a compile error.
+ */
+const withNull = (type) => type.includes("null") ? type : `${type} | null`;
 function tsTypeForSchemaField(def, variant = "read") {
     if (def.type === "single_select" || def.type === "multiple_select") {
         const options = def.template
@@ -166,13 +196,19 @@ function tsTypeForSchemaField(def, variant = "read") {
                 .map((o) => `"${o.label.replace(/"/g, '\\"')}"`)
                 .join(" | ");
             const union = `${literals} | string`;
-            if (def.type === "multiple_select")
-                return `(${union})[]`;
-            return union;
+            const read = def.type === "multiple_select" ? `(${union})[] | null` : `${union} | null`;
+            if (variant === "write") {
+                return def.type === "multiple_select"
+                    ? `${union} | (${union})[] | null`
+                    : `${union} | null`;
+            }
+            return read;
         }
     }
-    if (variant === "write" && FIELD_INPUT_TYPE_MAP[def.type]) {
-        return FIELD_INPUT_TYPE_MAP[def.type];
+    if (variant === "write") {
+        const write = FIELD_INPUT_TYPE_MAP[def.type] ?? FIELD_TYPE_MAP[def.type];
+        if (write)
+            return withNull(write);
     }
     if (FIELD_TYPE_MAP[def.type])
         return FIELD_TYPE_MAP[def.type];
@@ -474,7 +510,11 @@ function generateDbTs(schema) {
             if (jsdoc) {
                 lines.push(`  /** ${jsdoc} */`);
             }
-            lines.push(`  ${field.sdkName}: ${tsType};`);
+            // Optional, matching the pre-monorepo type (`required: ['id']` — "none of
+            // these are required to be defined aside from 'id'"). A `fields:`
+            // projection omits every key it wasn't asked for, so any field really can
+            // be absent on a read.
+            lines.push(`  ${field.sdkName}?: ${tsType};`);
         }
         lines.push("};");
         lines.push("");
@@ -712,14 +752,18 @@ const AIRTABLE_FIELD_TYPE_MAP = {
     currency: "number",
     percent: "number",
     rating: "number",
-    duration: "number",
+    // Formatted to "HH:mm:ss" before it reaches the app — `formatAirtableDuration`
+    // in BOTH dispatches. Unlike the Zite DB's, which is DECIMAL seconds.
+    duration: "string",
     checkbox: "boolean",
     date: "string",
     dateTime: "string",
     singleSelect: "string",
     multipleSelects: "string[]",
     multipleAttachments: "AirtableAttachment[]",
-    multipleRecordLinks: "string[]",
+    // `string | string[]`, matching the pre-monorepo type — see the note on the
+    // Zite DB's `linked_record`.
+    multipleRecordLinks: "string | string[]",
     singleCollaborator: "{ id: string; email: string; name?: string }",
     multipleCollaborators: "Array<{ id: string; email: string; name?: string }>",
     // Read-only fields
@@ -732,7 +776,8 @@ const AIRTABLE_FIELD_TYPE_MAP = {
     lastModifiedTime: "string",
     createdBy: "{ id: string; email: string; name?: string }",
     lastModifiedBy: "{ id: string; email: string; name?: string }",
-    button: "unknown",
+    // Both dispatches extract the URL string off the button object.
+    button: "string",
     externalSyncSource: "unknown",
     aiText: "string",
 };

package/dist/esm/sync/lib.js

@@ -1,32 +1,46 @@
 import { parse } from "@babel/parser";
 const AUTH_USERS_TABLE_ID = "zite_user";
-/** What a field's value looks like when a record is READ back. */
+/**
+ * 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.
+ */
 const FIELD_TYPE_MAP = {
+    // Text: NULL is rewritten to '' on read, so these genuinely can't be null.
     single_line_text: "string",
     long_text: "string",
     rich_text: "string",
     email: "string",
     url: "string",
     phone_number: "string",
-    number: "number",
-    currency: "number",
-    percent: "number",
-    rating: "number",
-    duration: "number",
-    single_select: "string",
-    multiple_select: "string[]",
-    checkbox: "boolean",
+    number: "number | null",
+    currency: "number | null",
+    percent: "number | null",
+    rating: "number | null",
+    // 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[]",
-    // base-runner normalizes both of these to an array on write and stores them
-    // that way, so a read never produces a bare string.
-    linked_record: "string[]",
-    user: "string[]",
+    attachments: "ZiteAttachment[] | null",
+    // `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",
     autonumber: "number",
-    source: "string",
+    // JSONB change metadata (`{ type: "PublicAPI", apiKeyId: 3 }`), not a string.
+    source: "unknown",
     formula: "unknown",
     created_at: "string",
     updated_at: "string",
@@ -37,9 +51,18 @@ const FIELD_TYPE_MAP = {
  * looser input than it stores.
  */
 const FIELD_INPUT_TYPE_MAP = {
-    attachments: "ZiteAttachmentInput[]",
-    linked_record: "string | string[] | null",
-    user: "string | string[] | null",
+    attachments: "ZiteAttachmentInput[] | ZiteAttachmentInput",
+    linked_record: "string | string[]",
+    user: "string | string[]",
+    multiple_select: "string | string[]",
+    date: "string | Date",
+    datetime: "string | Date",
+    number: "string | number",
+    currency: "string | number",
+    percent: "string | number",
+    rating: "string | number",
+    duration: "string | number",
+    checkbox: "string | boolean",
 };
 /**
  * Computed and system-managed fields, omitted from the generated input type
@@ -146,6 +169,13 @@ function keepValidSdkName(sdkName) {
         return undefined;
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(sdkName) ? sdkName : undefined;
 }
+/**
+ * `null` is how you CLEAR a cell — every scalar write schema in
+ * `flexible-inputs.ts` ends in `.nullable()` and update runs with
+ * `allowExplicitNull`. A write type without it makes the documented way to
+ * empty a field a compile error.
+ */
+const withNull = (type) => type.includes("null") ? type : `${type} | null`;
 function tsTypeForSchemaField(def, variant = "read") {
     if (def.type === "single_select" || def.type === "multiple_select") {
         const options = def.template
@@ -156,13 +186,19 @@ function tsTypeForSchemaField(def, variant = "read") {
                 .map((o) => `"${o.label.replace(/"/g, '\\"')}"`)
                 .join(" | ");
             const union = `${literals} | string`;
-            if (def.type === "multiple_select")
-                return `(${union})[]`;
-            return union;
+            const read = def.type === "multiple_select" ? `(${union})[] | null` : `${union} | null`;
+            if (variant === "write") {
+                return def.type === "multiple_select"
+                    ? `${union} | (${union})[] | null`
+                    : `${union} | null`;
+            }
+            return read;
         }
     }
-    if (variant === "write" && FIELD_INPUT_TYPE_MAP[def.type]) {
-        return FIELD_INPUT_TYPE_MAP[def.type];
+    if (variant === "write") {
+        const write = FIELD_INPUT_TYPE_MAP[def.type] ?? FIELD_TYPE_MAP[def.type];
+        if (write)
+            return withNull(write);
     }
     if (FIELD_TYPE_MAP[def.type])
         return FIELD_TYPE_MAP[def.type];
@@ -464,7 +500,11 @@ export function generateDbTs(schema) {
             if (jsdoc) {
                 lines.push(`  /** ${jsdoc} */`);
             }
-            lines.push(`  ${field.sdkName}: ${tsType};`);
+            // Optional, matching the pre-monorepo type (`required: ['id']` — "none of
+            // these are required to be defined aside from 'id'"). A `fields:`
+            // projection omits every key it wasn't asked for, so any field really can
+            // be absent on a read.
+            lines.push(`  ${field.sdkName}?: ${tsType};`);
         }
         lines.push("};");
         lines.push("");
@@ -702,14 +742,18 @@ const AIRTABLE_FIELD_TYPE_MAP = {
     currency: "number",
     percent: "number",
     rating: "number",
-    duration: "number",
+    // Formatted to "HH:mm:ss" before it reaches the app — `formatAirtableDuration`
+    // in BOTH dispatches. Unlike the Zite DB's, which is DECIMAL seconds.
+    duration: "string",
     checkbox: "boolean",
     date: "string",
     dateTime: "string",
     singleSelect: "string",
     multipleSelects: "string[]",
     multipleAttachments: "AirtableAttachment[]",
-    multipleRecordLinks: "string[]",
+    // `string | string[]`, matching the pre-monorepo type — see the note on the
+    // Zite DB's `linked_record`.
+    multipleRecordLinks: "string | string[]",
     singleCollaborator: "{ id: string; email: string; name?: string }",
     multipleCollaborators: "Array<{ id: string; email: string; name?: string }>",
     // Read-only fields
@@ -722,7 +766,8 @@ const AIRTABLE_FIELD_TYPE_MAP = {
     lastModifiedTime: "string",
     createdBy: "{ id: string; email: string; name?: string }",
     lastModifiedBy: "{ id: string; email: string; name?: string }",
-    button: "unknown",
+    // Both dispatches extract the URL string off the button object.
+    button: "string",
     externalSyncSource: "unknown",
     aiText: "string",
 };

package/package.json

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