zitejs 0.9.98 → 0.9.100

package/dist/cjs/runtime/index.d.ts

@@ -15,9 +15,9 @@ export type FilterCondition<V> = {
     contains?: any;
     /** Not equal, or — against `null` — "is set". */
     not?: V | null;
-    /** Empty array means "no filter", not "match nothing". */
+    /** An empty array matches NOTHING — the SDK's filters convert to the nested format, where `in: []` is "is one of nothing". */
     in?: V extends Array<infer E> ? E[] : V[];
-    /** Empty array means "no filter", not "match everything". */
+    /** An empty array applies no filter at all — "is not one of nothing" is always true. */
     notIn?: V extends Array<infer E> ? E[] : V[];
     lt?: V | number | Date;
     lte?: V | number | Date;
@@ -27,10 +27,9 @@ export type FilterCondition<V> = {
 /** Pre-monorepo name for {@link FilterCondition}. Kept so migrated app code that spells the type out still compiles. */
 export type FilterOperators<V> = FilterCondition<V> | V;
 /**
- * Airtable's filter set is the shared one plus two of its own, both compiled to
- * formulas in `integrations/airtable/formulas.ts`:
+ * Airtable's filter set is the shared one plus `ilike`, compiled to a formula in
+ * `integrations/airtable/formulas.ts`:
  *
- * - `equals` — explicit equality, alongside the bare-value shorthand.
  * - `ilike` — case-insensitive equality (`LOWER(f) = LOWER(v)`). Load-bearing:
  *   the `zite.auth.ts` generated for a migrated user-sync app matches rostered
  *   emails with it, because Airtable compares text case-sensitively while Zite
@@ -38,9 +37,18 @@ export type FilterOperators<V> = FilterCondition<V> | V;
  *
  * Kept separate from `FilterCondition` rather than merged into it, so a Zite DB
  * filter can't offer an operator its runtime ignores.
+ *
+ * NOT `equals`, despite `formulas.ts` having a `case 'equals'`: that case only
+ * fires for the bare-value shorthand. `equals` is absent from
+ * `WhereConditionOperators`, so `isNestedCondition` doesn't recognize the
+ * object, the whole `{ equals: … }` is stringified as the operand, and Airtable
+ * 422s on `{Email}=[object Object]`.
+ *
+ * One operator per field on this path — `formulas.ts` reads
+ * `Object.keys(condition)[0]` and drops the rest, unlike the Zite DB filter
+ * builder which iterates them all.
  */
 export type AirtableFilterCondition<V> = FilterCondition<V> & {
-    equals?: V;
     ilike?: V | V[];
 };
 export type AirtableRecordFilters<T> = {
@@ -73,6 +81,13 @@ export type FieldSelector<T> = Extract<keyof T, string> | (string & {});
 export interface TableFindAllOptions<T = Record<string, unknown>> {
     limit?: number;
     offset?: number;
+    /**
+     * IGNORED on the table path. `DatabasesFindAllParamsSchema` has no `sort`
+     * key, so zod strips it before either dispatch, and neither destructures it.
+     * Kept in the type because removing it would only turn a silent no-op into a
+     * compile error for apps already passing it — the real fix is to forward it.
+     * It DOES work on `zite.auth.findAllUsers`, which is dispatched separately.
+     */
     sort?: unknown[];
     filters?: RecordFilters<T>;
     fields?: Array<FieldSelector<T>>;

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];
@@ -411,8 +447,8 @@ function generateDbTs(schema) {
     lines.push("//   .findAll({ filters?, sort?, offset?, limit?, fields? }) → { records: T[], hasMore: boolean }");
     lines.push("//     filters: { fieldName: value } for equality, or { fieldName: { <op>: value } }");
     lines.push("//     operators: contains, not, in, notIn, lt, lte, gt, gte");
-    lines.push('//       `not: null` means "is set"; `in`/`notIn` with an empty array apply NO filter');
-    lines.push("//     sort: [{ field: 'fieldName', direction: 'asc' | 'desc' }]");
+    lines.push('//       `not: null` means "is set". An empty `in: []` matches nothing; an', '//       empty `notIn: []` applies no filter.');
+    lines.push("//     sort is currently IGNORED here — it is stripped before the request.", "//       (it does work on zite.auth.findAllUsers). Order in SQL instead.");
     lines.push("//     limit defaults to 500, max 2000; offset is a row count (a number)");
     lines.push("//   .findOne({ id?, filters?, fields? }) → T | undefined");
     lines.push("//   .create({ record }) → T");
@@ -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/runtime/index.d.ts

@@ -15,9 +15,9 @@ export type FilterCondition<V> = {
     contains?: any;
     /** Not equal, or — against `null` — "is set". */
     not?: V | null;
-    /** Empty array means "no filter", not "match nothing". */
+    /** An empty array matches NOTHING — the SDK's filters convert to the nested format, where `in: []` is "is one of nothing". */
     in?: V extends Array<infer E> ? E[] : V[];
-    /** Empty array means "no filter", not "match everything". */
+    /** An empty array applies no filter at all — "is not one of nothing" is always true. */
     notIn?: V extends Array<infer E> ? E[] : V[];
     lt?: V | number | Date;
     lte?: V | number | Date;
@@ -27,10 +27,9 @@ export type FilterCondition<V> = {
 /** Pre-monorepo name for {@link FilterCondition}. Kept so migrated app code that spells the type out still compiles. */
 export type FilterOperators<V> = FilterCondition<V> | V;
 /**
- * Airtable's filter set is the shared one plus two of its own, both compiled to
- * formulas in `integrations/airtable/formulas.ts`:
+ * Airtable's filter set is the shared one plus `ilike`, compiled to a formula in
+ * `integrations/airtable/formulas.ts`:
  *
- * - `equals` — explicit equality, alongside the bare-value shorthand.
  * - `ilike` — case-insensitive equality (`LOWER(f) = LOWER(v)`). Load-bearing:
  *   the `zite.auth.ts` generated for a migrated user-sync app matches rostered
  *   emails with it, because Airtable compares text case-sensitively while Zite
@@ -38,9 +37,18 @@ export type FilterOperators<V> = FilterCondition<V> | V;
  *
  * Kept separate from `FilterCondition` rather than merged into it, so a Zite DB
  * filter can't offer an operator its runtime ignores.
+ *
+ * NOT `equals`, despite `formulas.ts` having a `case 'equals'`: that case only
+ * fires for the bare-value shorthand. `equals` is absent from
+ * `WhereConditionOperators`, so `isNestedCondition` doesn't recognize the
+ * object, the whole `{ equals: … }` is stringified as the operand, and Airtable
+ * 422s on `{Email}=[object Object]`.
+ *
+ * One operator per field on this path — `formulas.ts` reads
+ * `Object.keys(condition)[0]` and drops the rest, unlike the Zite DB filter
+ * builder which iterates them all.
  */
 export type AirtableFilterCondition<V> = FilterCondition<V> & {
-    equals?: V;
     ilike?: V | V[];
 };
 export type AirtableRecordFilters<T> = {
@@ -73,6 +81,13 @@ export type FieldSelector<T> = Extract<keyof T, string> | (string & {});
 export interface TableFindAllOptions<T = Record<string, unknown>> {
     limit?: number;
     offset?: number;
+    /**
+     * IGNORED on the table path. `DatabasesFindAllParamsSchema` has no `sort`
+     * key, so zod strips it before either dispatch, and neither destructures it.
+     * Kept in the type because removing it would only turn a silent no-op into a
+     * compile error for apps already passing it — the real fix is to forward it.
+     * It DOES work on `zite.auth.findAllUsers`, which is dispatched separately.
+     */
     sort?: unknown[];
     filters?: RecordFilters<T>;
     fields?: Array<FieldSelector<T>>;

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];
@@ -401,8 +437,8 @@ export function generateDbTs(schema) {
     lines.push("//   .findAll({ filters?, sort?, offset?, limit?, fields? }) → { records: T[], hasMore: boolean }");
     lines.push("//     filters: { fieldName: value } for equality, or { fieldName: { <op>: value } }");
     lines.push("//     operators: contains, not, in, notIn, lt, lte, gt, gte");
-    lines.push('//       `not: null` means "is set"; `in`/`notIn` with an empty array apply NO filter');
-    lines.push("//     sort: [{ field: 'fieldName', direction: 'asc' | 'desc' }]");
+    lines.push('//       `not: null` means "is set". An empty `in: []` matches nothing; an', '//       empty `notIn: []` applies no filter.');
+    lines.push("//     sort is currently IGNORED here — it is stripped before the request.", "//       (it does work on zite.auth.findAllUsers). Order in SQL instead.");
     lines.push("//     limit defaults to 500, max 2000; offset is a row count (a number)");
     lines.push("//   .findOne({ id?, filters?, fields? }) → T | undefined");
     lines.push("//   .create({ record }) → T");
@@ -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.98",
+  "version": "0.9.100",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "main": "./dist/cjs/index.js",