@terrascale/sdk 0.0.8 → 0.0.9

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.9 — declared JSON Schema models
+
+Node tooling at `@terrascale/sdk/codegen` generates document, create and
+merge-patch body types from `collection.getSchema()` or a schema file. Install
+the exact tooling peer `json-schema-to-typescript@16.0.0`; the `terrascale-models`
+command is separate from browser/runtime entrypoints. Unsupported constructs
+produce JSON Pointer diagnostics. Runtime validation remains authoritative.
+
 ## 0.0.7 — live shape reconnect, browser bootstrap and read replica
 
 `subscribeShape` keeps its state and retries the same position after a lost

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",
@@ -70,10 +70,16 @@
       "workerd": null,
       "browser": null,
       "node": "./src/postgres.js"
+    },
+    "./codegen": {
+      "types": "./types/codegen.d.ts",
+      "browser": null,
+      "node": "./src/codegen.js"
     }
   },
   "bin": {
-    "terrascale-local": "./src/local/cli.js"
+    "terrascale-local": "./src/local/cli.js",
+    "terrascale-models": "./src/codegen-cli.js"
   },
   "files": [
     "src",
@@ -109,7 +115,8 @@
     "@better-auth/core": "1.7.2",
     "react": ">=18.2.0 <20.0.0",
     "pg": "8.23.0",
-    "@tanstack/db": "0.9.2"
+    "@tanstack/db": "0.9.2",
+    "json-schema-to-typescript": "16.0.0"
   },
   "peerDependenciesMeta": {
     "@better-auth/core": {
@@ -123,6 +130,9 @@
     },
     "@tanstack/db": {
       "optional": true
+    },
+    "json-schema-to-typescript": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -140,7 +150,8 @@
     "@types/react": "19.2.14",
     "@types/react-test-renderer": "19.1.0",
     "pg": "8.23.0",
-    "@types/pg": "8.23.1"
+    "@types/pg": "8.23.1",
+    "json-schema-to-typescript": "16.0.0"
   },
   "engines": {
     "node": "22.x || 24.x",

package/src/codegen-cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { generateDocumentModels } from "./codegen.js";
+import { parseExactJson } from "./v1/json.js";
+const [source, name, output, ...extra] = process.argv.slice(2);
+if (!source || !name || !output || extra.length) {
+  process.stderr.write("Usage: terrascale-models declared-schema.json ModelName models.ts\nInput is the schema itself; use @terrascale/sdk/codegen to fetch a live declaration.\n");
+  process.exitCode = 1;
+} else {
+  try {
+    const generated = await generateDocumentModels(parseExactJson(await readFile(source, "utf8")), name);
+    await writeFile(output, generated, "utf8");
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : "Model generation failed"}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/codegen.js

@@ -0,0 +1,137 @@
+// Node-only tooling. Never imported by the browser SDK entrypoint.
+import { compile } from "json-schema-to-typescript";
+import { isJsonObject, ExactDecimal } from "./v1/json.js";
+/** @import { V1Collection } from "./v1/terrabase-v1.js" */
+/** @typedef {Record<string, unknown>} Schema */
+const dialect = "https://json-schema.org/draft/2020-12/schema";
+const supported = new Set(["$schema", "type", "properties", "required", "additionalProperties", "items", "enum", "const", "readOnly", "title", "description", "default", "examples", "format", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "minLength", "maxLength", "minItems", "maxItems", "uniqueItems", "minProperties", "maxProperties"]);
+/** @param {string} pointer @param {string} message @returns {never} */
+function diagnostic(pointer, message) { throw new TypeError(`Collection model ${pointer || "/"}: ${message}`); }
+/** @param {string} pointer @param {string} key */
+function at(pointer, key) { return `${pointer}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`; }
+
+/**
+ * Generate body models from a declared Draft 2020-12 schema, never inferred samples.
+ * Runtime validation remains authoritative; constraints such as ranges and lengths
+ * cannot be expressed by TypeScript. Patch is an RFC 7396 merge-patch body.
+ * @param {unknown} input
+ * @param {string} name A TypeScript identifier prefix.
+ * @returns {Promise<string>}
+ */
+export async function generateDocumentModels(input, name) {
+  if (!/^[A-Z][A-Za-z0-9]*$/u.test(name)) throw new TypeError("Model name must start with A-Z and contain only letters and digits.");
+  // Also reject cyclic objects, lossy numbers, and excessive input before compilation.
+  let values = 0;
+  /** @param {unknown} value @param {number} depth */
+  function bounded(value, depth) {
+    if (++values > 4093 || depth > 15) diagnostic("", "schema exceeds 4093 values or 15 nesting levels.");
+    if (value instanceof ExactDecimal || (typeof value === "number" && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))) diagnostic("", "exact numeric literals outside JavaScript's safe range are unsupported.");
+    if (Array.isArray(value) || isJsonObject(value)) for (const child of Object.values(value)) bounded(child, depth + 1);
+  }
+  bounded(input, 0);
+  if (Buffer.byteLength(JSON.stringify(input) ?? "") > 65536) diagnostic("", "schema exceeds 64 KiB.");
+  if (!isJsonObject(input) || input.type !== "object") diagnostic("/type", "document root must declare type: object.");
+  const models = [];
+  for (const mode of /** @type {const} */ (["Document", "Create", "Patch"])) {
+    const schema = convert(input, "", mode);
+    const identifier = `${name}${mode}`;
+    const output = await compile(/** @type {import("json-schema-to-typescript").JSONSchema} */ (schema), identifier, {
+      bannerComment: "", format: false, unknownAny: true, ignoreMinAndMaxItems: true,
+      $refOptions: { resolve: { file: false, http: false } },
+    });
+    // Object aliases remain assignable to the SDK's JSON object input type.
+    models.push(output.replace(`export interface ${identifier} {`, `export type ${identifier} = {`).trim());
+  }
+  return `// Generated by @terrascale/sdk/codegen (json-schema-to-typescript 16.0.0). Do not edit.\n// Bodies only; id/version are server envelope fields. Runtime validation is authoritative.\n\n${models.join("\n\n")}\n`;
+}
+
+/** @param {unknown} input @param {string} pointer @param {"Document" | "Create" | "Patch"} mode @returns {Schema | boolean} */
+function convert(input, pointer, mode) {
+  if (input === false) return false;
+  const jsonType = `import("@terrascale/sdk").${mode === "Document" ? "V1JsonValue" : "V1JsonInput"}`;
+  if (input === true) return { tsType: jsonType };
+  if (!isJsonObject(input)) diagnostic(pointer, "expected a schema object or boolean.");
+  for (const key of Object.keys(input).sort()) if (!supported.has(key)) diagnostic(at(pointer, key), `unsupported keyword ${key}; inline references or simplify the schema to the documented subset.`);
+  for (const key of ["minLength", "maxLength", "minItems", "maxItems", "minProperties", "maxProperties"]) if (input[key] !== undefined && (typeof input[key] !== "number" || !Number.isSafeInteger(input[key]) || input[key] < 0)) diagnostic(at(pointer, key), "expected a nonnegative safe integer.");
+  for (const key of ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"]) if (input[key] !== undefined && (typeof input[key] !== "number" || (key === "multipleOf" && input[key] <= 0))) diagnostic(at(pointer, key), "expected a number (positive for multipleOf).");
+  for (const key of ["title", "description", "format"]) if (input[key] !== undefined && typeof input[key] !== "string") diagnostic(at(pointer, key), "expected a string annotation.");
+  if (input.examples !== undefined && !Array.isArray(input.examples)) diagnostic(at(pointer, "examples"), "expected an array.");
+  if (input.uniqueItems !== undefined && typeof input.uniqueItems !== "boolean") diagnostic(at(pointer, "uniqueItems"), "expected a boolean.");
+  if (input.$schema !== undefined && input.$schema !== dialect) diagnostic(at(pointer, "$schema"), `only ${dialect} is supported.`);
+  const types = Array.isArray(input.type) ? input.type : [input.type];
+  const kinds = types.filter(type => type !== "null");
+  if (new Set(types).size !== types.length || kinds.length > 1 || types.length === 0 || types.some(type => !["object", "array", "string", "number", "integer", "boolean", "null"].includes(String(type)))) diagnostic(at(pointer, "type"), "declare one type, optionally unioned with null.");
+  const kind = kinds[0];
+  const nullable = types.includes("null");
+  for (const key of ["properties", "required", "additionalProperties"]) if (Object.hasOwn(input, key) && kind !== "object") diagnostic(at(pointer, key), "this keyword is supported only with an object type.");
+  if (Object.hasOwn(input, "items") && kind !== "array") diagnostic(at(pointer, "items"), "items is supported only with an array type.");
+  if (input.readOnly !== undefined && typeof input.readOnly !== "boolean") diagnostic(at(pointer, "readOnly"), "expected a boolean annotation.");
+  /** @type {Schema} */
+  const result = { type: input.type };
+  if (typeof input.description === "string") result.description = input.description;
+  for (const key of ["enum", "const"]) {
+    if (!Object.hasOwn(input, key)) continue;
+    if (kind === "object" || kind === "array") diagnostic(at(pointer, key), "container literal constraints are unsupported; use type: null for a null-only value.");
+    const literals = key === "enum" ? input[key] : [input[key]];
+    if (!Array.isArray(literals) || literals.length === 0 || literals.some(value => value !== null && !["string", "number", "boolean"].includes(typeof value))) diagnostic(at(pointer, key), "only nonempty scalar literals are supported.");
+    if (literals.some(value => !types.some(type => type === "null" ? value === null : type === "integer" ? typeof value === "number" && Number.isInteger(value) : typeof value === type))) diagnostic(at(pointer, key), "literal/type intersections are unsupported; each literal must satisfy the declared type.");
+    result[key] = input[key];
+  }
+  if (Array.isArray(input.enum) && Object.hasOwn(input, "const") && !input.enum.includes(input.const ?? null)) diagnostic(at(pointer, "const"), "const must belong to enum.");
+  if ((kind === "number" || kind === "integer") && result.enum === undefined && result.const === undefined) result.tsType = `number | import("@terrascale/sdk").ExactDecimal${mode === "Document" ? "" : " | bigint"}${nullable ? " | null" : ""}`;
+  if (kind === "array") {
+    if (input.items === undefined) diagnostic(at(pointer, "items"), "declare the array item schema (or true for arbitrary JSON).");
+    result.items = convert(input.items, at(pointer, "items"), mode === "Patch" ? "Create" : mode);
+  }
+  if (kind === "object") {
+    const properties = input.properties === undefined ? {} : input.properties;
+    if (!isJsonObject(properties)) diagnostic(at(pointer, "properties"), "expected a property map.");
+    const required = input.required === undefined ? [] : input.required;
+    if (!Array.isArray(required) || required.some(key => typeof key !== "string" || !Object.hasOwn(properties, key))) diagnostic(at(pointer, "required"), "required must list declared property names.");
+    if (new Set(required).size !== required.length) diagnostic(at(pointer, "required"), "required names must be unique.");
+    const entries = Object.keys(properties).sort().map(key => {
+      const property = properties[key];
+      const location = at(at(pointer, "properties"), key);
+      // Validate even omitted read-only fields, so unsupported constructs never hide.
+      let converted = convert(property, location, mode);
+      if (mode !== "Document" && isJsonObject(property) && property.readOnly === true) converted = false;
+      else if (mode === "Patch") {
+        // null deletes in RFC 7396, including when the stored field permits null.
+        if (!required.includes(key)) converted = { anyOf: [converted, { type: "null" }] };
+        else if (property === true) converted = { tsType: `Exclude<${jsonType}, null>` };
+        else if (isJsonObject(property)) {
+          /** @type {Schema & {type: unknown[]}} */
+          const nonnull = { ...property, type: (Array.isArray(property.type) ? property.type : [property.type]).filter(t => t !== "null") };
+          if (Array.isArray(nonnull.enum)) nonnull.enum = nonnull.enum.filter(value => value !== null);
+          converted = nonnull.type.length === 0 || nonnull.const === null || (Array.isArray(nonnull.enum) && nonnull.enum.length === 0) ? false : convert(nonnull, location, mode);
+        }
+      }
+      return [key, converted];
+    });
+    for (const key of required) if (typeof key === "string" && isJsonObject(properties[key]) && properties[key].readOnly === true) diagnostic(at(at(pointer, "properties"), key), "required readOnly fields cannot be populated by the producer; default is not server generation. Make this field writable or optional.");
+    result.properties = Object.fromEntries(entries);
+    result.required = mode === "Patch" ? [] : required.filter(key => typeof key === "string" && (mode === "Document" || !isJsonObject(properties[key]) || properties[key].readOnly !== true));
+    const additional = input.additionalProperties;
+    if (additional === undefined || additional === true) {
+      // Separate the JSON index signature so the generator cannot widen it with
+      // undefined for optional properties (which SDK JSON inputs prohibit).
+      result.additionalProperties = false;
+      result.type = "object";
+      const object = { allOf: [result, { tsType: `Record<string, ${jsonType}>` }] };
+      return nullable ? { anyOf: [object, { type: "null" }] } : object;
+    }
+    if (additional !== false && Object.keys(properties).length) diagnostic(at(pointer, "additionalProperties"), "typed additional properties with named properties cannot be represented exactly; use a pure map or a closed object.");
+    let extra = convert(additional, at(pointer, "additionalProperties"), mode);
+    if (additional !== false && mode === "Patch") extra = { anyOf: [extra, { type: "null" }] };
+    result.additionalProperties = extra;
+    if (additional === false && entries.length === 0) return { tsType: `Record<string, never>${nullable ? " | null" : ""}` };
+  }
+  return result;
+}
+
+/** Fetch the authorized declared schema using the public SDK operation. @param {V1Collection} collection @param {string} name @param {import("./v1/terrabase-v1.js").V1RequestOptions} [options] */
+export async function generateCollectionModels(collection, name, options = {}) {
+  const { schema } = await collection.getSchema(options);
+  if (schema === null) diagnostic("", "collection has no declared JSON Schema; attach one with collection.putSchema(). Inference is not a declaration.");
+  return generateDocumentModels(schema, name);
+}

package/types/codegen-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/codegen.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate body models from a declared Draft 2020-12 schema, never inferred samples.
+ * Runtime validation remains authoritative; constraints such as ranges and lengths
+ * cannot be expressed by TypeScript. Patch is an RFC 7396 merge-patch body.
+ * @param {unknown} input
+ * @param {string} name A TypeScript identifier prefix.
+ * @returns {Promise<string>}
+ */
+export function generateDocumentModels(input: unknown, name: string): Promise<string>;
+/** Fetch the authorized declared schema using the public SDK operation. @param {V1Collection} collection @param {string} name @param {import("./v1/terrabase-v1.js").V1RequestOptions} [options] */
+export function generateCollectionModels(collection: V1Collection, name: string, options?: import("./v1/terrabase-v1.js").V1RequestOptions): Promise<string>;
+export type Schema = Record<string, unknown>;
+import type { V1Collection } from "./v1/terrabase-v1.js";