@terrascale/sdk 0.0.2 → 0.0.4

package/src/database-codec.js

@@ -1,3 +1,5 @@
+import { requireId as requireDatabaseId } from "./ids.js";
+export { requireId as requireDatabaseId } from "./ids.js";
 /**
  * @import {
  *   DatabaseAuthority, DatabaseCommit, DatabaseCommitReceipt, DatabaseCondition, DatabaseEvent,
@@ -20,18 +22,6 @@ const maximumBodyBytes = 4 * 1024 * 1024;
 const maximumValueBytes = 1024 * 1024;
 const scalarTypes = new Set(["bool", "i64", "utf8", "bytes"]);
 
-/**
- * @param {unknown} value
- * @param {string} [name]
- * @returns {string}
- */
-export function requireDatabaseUuid(value, name = "UUID") {
-  if (typeof value !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(value)) {
-    throw new TypeError(`${name} must be a canonical lowercase UUID.`);
-  }
-  return value;
-}
-
 /**
  * @param {unknown} value
  * @param {string} [name]
@@ -295,7 +285,7 @@ function observedToWire(entries) {
   let previous = "";
   return array(entries).map(raw => {
     const entry = object(raw, ["replica", "incarnation", "sequence"]);
-    const replica = requireDatabaseUuid(entry.replica, "replica");
+    const replica = requireDatabaseId(entry.replica, "replica");
     const incarnation = hex(entry.incarnation, 16, "incarnation");
     const order = replica + incarnation;
     if (order <= previous) throw new TypeError("Observed origins must be strictly increasing.");
@@ -311,7 +301,7 @@ function observedToWire(entries) {
 function observedFromWire(raw) {
   const entries = array(raw).map(value => {
     const entry = object(value, ["replica", "incarnation", "sequence"]);
-    return { replica: requireDatabaseUuid(entry.replica, "replica"), incarnation: hex(entry.incarnation, 16, "incarnation"), sequence: decimal(entry.sequence, "sequence", true) };
+    return { replica: requireDatabaseId(entry.replica, "replica"), incarnation: hex(entry.incarnation, 16, "incarnation"), sequence: decimal(entry.sequence, "sequence", true) };
   });
   observedToWire(entries);
   return entries;
@@ -324,8 +314,8 @@ function observedFromWire(raw) {
 function eventFromWire(raw) {
   const entry = object(raw, ["database", "shard", "replica", "incarnation", "sequence"]);
   return {
-    database: requireDatabaseUuid(entry.database, "database"), shard: decimal(entry.shard, "shard"),
-    replica: requireDatabaseUuid(entry.replica, "replica"), incarnation: hex(entry.incarnation, 16, "incarnation"),
+    database: requireDatabaseId(entry.database, "database"), shard: decimal(entry.shard, "shard"),
+    replica: requireDatabaseId(entry.replica, "replica"), incarnation: hex(entry.incarnation, 16, "incarnation"),
     sequence: decimal(entry.sequence, "sequence", true),
   };
 }
@@ -430,7 +420,7 @@ function rowsFromWire(raw) {
   let previous = "";
   return array(raw, 128).map(rawRow => {
     const entry = object(rawRow, ["document", "point"]);
-    const document = requireDatabaseUuid(entry.document, "document");
+    const document = requireDatabaseId(entry.document, "document");
     if (document <= previous) throw new TypeError("Query documents must be strictly increasing.");
     previous = document;
     return { document, point: decodeDatabasePoint(entry.point) };
@@ -486,7 +476,7 @@ export function decodeDatabaseSubscription(raw) {
     previous = sequence;
     return { sequence, effects: array(group.effects, 128).map(rawEffect => {
       const effect = object(rawEffect, ["document", "point"]);
-      return { document: requireDatabaseUuid(effect.document, "document"), point: effect.point === null ? null : decodeDatabasePoint(effect.point) };
+      return { document: requireDatabaseId(effect.document, "document"), point: effect.point === null ? null : decodeDatabasePoint(effect.point) };
     }) };
   });
   return { version: 1, phase: "poll", groups, poll_cursor: cursor(entry.poll_cursor) };
@@ -501,7 +491,7 @@ export function encodeDatabaseAuthority(authority) {
   object(authority, ["mode", "generation", "writer"]);
   if (authority.mode !== "single_writer") throw new TypeError("Unsupported authority mode.");
   const writer = object(authority.writer, ["replica", "incarnation"]);
-  return { mode: "single_writer", generation: requireDatabaseU64(authority.generation, "authority generation", true).toString(), writer: { replica: requireDatabaseUuid(writer.replica, "writer"), incarnation: hex(writer.incarnation, 16, "incarnation") } };
+  return { mode: "single_writer", generation: requireDatabaseU64(authority.generation, "authority generation", true).toString(), writer: { replica: requireDatabaseId(writer.replica, "writer"), incarnation: hex(writer.incarnation, 16, "incarnation") } };
 }
 
 /**
@@ -514,7 +504,7 @@ export function decodeDatabaseAuthority(raw) {
   const entry = object(raw, ["mode", "generation", "writer"]);
   if (entry.mode !== "single_writer") throw new TypeError("Unsupported authority mode.");
   const writer = object(entry.writer, ["replica", "incarnation"]);
-  return { mode: "single_writer", generation: decimal(entry.generation, "authority generation", true), writer: { replica: requireDatabaseUuid(writer.replica, "writer"), incarnation: hex(writer.incarnation, 16, "incarnation") } };
+  return { mode: "single_writer", generation: decimal(entry.generation, "authority generation", true), writer: { replica: requireDatabaseId(writer.replica, "writer"), incarnation: hex(writer.incarnation, 16, "incarnation") } };
 }
 
 /**
@@ -569,7 +559,7 @@ function writeToWire(write, authority) {
     : (object(write.value, ["kind", "fields"]), { kind: "live", fields: fieldsToWire(write.value.fields, 1, { nodes: 0 }) });
   if (write.value.kind !== "live" && write.value.kind !== "tombstone") throw new TypeError("Unsupported write kind.");
   if (value.kind === "live") validateNativeDocument(/** @type {readonly Json[]} */ (value.fields));
-  return { collection: requireDatabaseUuid(write.collection, "collection"), document: requireDatabaseUuid(write.document, "document"), schema_generation: requireDatabaseU64(write.schema_generation, "schema generation", true).toString(), schema_digest: hex(write.schema_digest, 32, "schema digest"), condition: conditionToWire(write.condition), observed: observedToWire(write.observed), value };
+  return { collection: requireDatabaseId(write.collection, "collection"), document: requireDatabaseId(write.document, "document"), schema_generation: requireDatabaseU64(write.schema_generation, "schema generation", true).toString(), schema_digest: hex(write.schema_digest, 32, "schema digest"), condition: conditionToWire(write.condition), observed: observedToWire(write.observed), value };
 }
 
 class Bytes {
@@ -603,7 +593,12 @@ class Bytes {
    * @param {string} value
    * @returns {void}
    */
-  uuid(value) { this.hex(value.replaceAll("-", "")); }
+  id(value) {
+    const alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    let bits = 0n;
+    for (const char of requireDatabaseId(value)) bits = (bits << 5n) | BigInt(alphabet.indexOf(char));
+    this.hex(bits.toString(16).padStart(32, "0"));
+  }
   /** @returns {Uint8Array} */
   finish() { const bytes = new Uint8Array(this.length); let offset = 0; for (const chunk of this.chunks) { bytes.set(chunk, offset); offset += chunk.length; } return bytes; }
 }
@@ -667,22 +662,22 @@ function validateNativeDocument(fields) {
 function effectBytes(scope, authority, writes) {
   const bytes = new Bytes();
   bytes.put(encoder.encode("TB-DOC-EFFECT-v1\0"));
-  bytes.uuid(requireDatabaseUuid(scope.tenant, "tenant")); bytes.uuid(requireDatabaseUuid(scope.database, "database")); bytes.integer(requireDatabaseU64(scope.shard, "shard"), 8);
+  bytes.id(requireDatabaseId(scope.tenant, "tenant")); bytes.id(requireDatabaseId(scope.database, "database")); bytes.integer(requireDatabaseU64(scope.shard, "shard"), 8);
   const singleWriter = authority.mode === "single_writer";
   bytes.integer(singleWriter ? 1n : 0n, 1);
   if (singleWriter) {
     const writer = object(authority.writer, ["replica", "incarnation"]);
-    bytes.integer(BigInt(/** @type {string} */ (authority.generation)), 8); bytes.uuid(/** @type {string} */ (writer.replica)); bytes.hex(/** @type {string} */ (writer.incarnation));
+    bytes.integer(BigInt(/** @type {string} */ (authority.generation)), 8); bytes.id(/** @type {string} */ (writer.replica)); bytes.hex(/** @type {string} */ (writer.incarnation));
   }
   bytes.integer(BigInt(writes.length), 8);
   for (const write of writes) {
-    bytes.uuid(/** @type {string} */ (write.collection)); bytes.uuid(/** @type {string} */ (write.document)); bytes.integer(BigInt(/** @type {string} */ (write.schema_generation)), 8); bytes.hex(/** @type {string} */ (write.schema_digest));
+    bytes.id(/** @type {string} */ (write.collection)); bytes.id(/** @type {string} */ (write.document)); bytes.integer(BigInt(/** @type {string} */ (write.schema_generation)), 8); bytes.hex(/** @type {string} */ (write.schema_digest));
     const condition = object(write.condition, ["kind"], ["version"]);
     bytes.integer(condition.kind === "none" ? 0n : condition.kind === "absent" ? 1n : 2n, 1);
     if (condition.kind === "version") bytes.hex(/** @type {string} */ (condition.version));
     const observed = array(write.observed);
     bytes.integer(BigInt(observed.length), 8);
-    for (const raw of observed) { const entry = object(raw, ["replica", "incarnation", "sequence"]); bytes.uuid(/** @type {string} */ (entry.replica)); bytes.hex(/** @type {string} */ (entry.incarnation)); bytes.integer(BigInt(/** @type {string} */ (entry.sequence)), 8); }
+    for (const raw of observed) { const entry = object(raw, ["replica", "incarnation", "sequence"]); bytes.id(/** @type {string} */ (entry.replica)); bytes.hex(/** @type {string} */ (entry.incarnation)); bytes.integer(BigInt(/** @type {string} */ (entry.sequence)), 8); }
     const value = object(write.value, ["kind"], ["fields"]);
     bytes.integer(value.kind === "tombstone" ? 0n : 1n, 1);
     if (value.kind === "live") {

package/src/database-types.js

@@ -1,20 +1,20 @@
 /**
- * The current TerraBase document protocol uses canonical UUID entity IDs.
- * @typedef {string} CanonicalUuid
+ * Entity identities are canonical uppercase ULIDs, including explicit local development.
+ * @typedef {import("./ids.js").EntityId} EntityId
  */
 
 /**
  * All 64-bit quantities stay bigint in JavaScript and decimal strings on the wire.
  * @typedef {{
- *   readonly tenant: CanonicalUuid;
- *   readonly database: CanonicalUuid;
+ *   readonly tenant: EntityId;
+ *   readonly database: EntityId;
  *   readonly shard: bigint;
  * }} DatabaseScope
  */
 
 /**
  * @typedef {{
- *   readonly collection: CanonicalUuid;
+ *   readonly collection: EntityId;
  *   readonly schema_generation: bigint;
  *   readonly schema_digest: string;
  * }} CollectionBinding
@@ -39,7 +39,7 @@
 
 /**
  * @typedef {{
- *   readonly replica: CanonicalUuid;
+ *   readonly replica: EntityId;
  *   readonly incarnation: string;
  *   readonly sequence: bigint;
  * }} DatabaseObserved
@@ -47,7 +47,7 @@
 
 /**
  * @typedef {DatabaseObserved & {
- *   readonly database: CanonicalUuid;
+ *   readonly database: EntityId;
  *   readonly shard: bigint;
  * }} DatabaseEvent
  */
@@ -58,7 +58,7 @@
  *   | {
  *     readonly mode: "single_writer";
  *     readonly generation: bigint;
- *     readonly writer: { readonly replica: CanonicalUuid; readonly incarnation: string };
+ *     readonly writer: { readonly replica: EntityId; readonly incarnation: string };
  *   }
  * )} DatabaseAuthority
  */
@@ -80,7 +80,7 @@
 
 /**
  * @typedef {CollectionBinding & {
- *   readonly document: CanonicalUuid;
+ *   readonly document: EntityId;
  *   readonly condition: DatabaseCondition;
  *   readonly observed: readonly DatabaseObserved[];
  *   readonly value: DatabaseWriteValue;
@@ -135,7 +135,7 @@
  * }} DatabaseQuery
  */
 
-/** @typedef {{ readonly document: CanonicalUuid; readonly point: DatabasePoint }} DatabaseQueryRow */
+/** @typedef {{ readonly document: EntityId; readonly point: DatabasePoint }} DatabaseQueryRow */
 
 /**
  * @typedef {{
@@ -202,7 +202,7 @@
  * )} DatabaseSubscriptionRequest
  */
 
-/** @typedef {{ readonly document: CanonicalUuid; readonly point: DatabasePoint | null }} DatabaseSubscriptionEffect */
+/** @typedef {{ readonly document: EntityId; readonly point: DatabasePoint | null }} DatabaseSubscriptionEffect */
 
 /**
  * @typedef {{

package/src/database-view.js

@@ -1,4 +1,4 @@
-import { encodeDatabaseSubscription, requireDatabaseUuid, requireDatabaseU64 } from "./database-codec.js";
+import { encodeDatabaseSubscription, requireDatabaseId, requireDatabaseU64 } from "./database-codec.js";
 /**
  * @import { TerraBaseClient } from "./local/legacy-client.js"
  * @import {
@@ -213,14 +213,14 @@ export class DatabaseSubscriptionView {
    */
   constructor(scope, options) {
     const capturedScope = Object.freeze({
-      tenant: requireDatabaseUuid(scope.tenant, "tenant"),
-      database: requireDatabaseUuid(scope.database, "database"),
+      tenant: requireDatabaseId(scope.tenant, "tenant"),
+      database: requireDatabaseId(scope.database, "database"),
       shard: requireDatabaseU64(scope.shard, "shard"),
     });
     const predicate = predicateCopy(options.predicate);
     const limit = boundedInteger(options.limit, 128, 128, "Snapshot page size");
     encodeDatabaseSubscription({ phase: "snapshot", predicate, limit });
-    this.binding = Object.freeze({ scope: capturedScope, collection: requireDatabaseUuid(options.collection, "collection"), predicate, limit });
+    this.binding = Object.freeze({ scope: capturedScope, collection: requireDatabaseId(options.collection, "collection"), predicate, limit });
     this.#maximumRows = boundedInteger(options.maximumRows, 10_000, 1_000_000, "Maximum rows");
   }
 
@@ -258,7 +258,7 @@ export class DatabaseSubscriptionView {
       if (response.rows.length > this.binding.limit) throw new DatabaseSubscriptionError("page_limit_exceeded");
       let previous = this.#snapshotRows.at(-1)?.document ?? "";
       const page = response.rows.map(row => {
-        const document = requireDatabaseUuid(row.document, "document");
+        const document = requireDatabaseId(row.document, "document");
         if (document <= previous) throw new DatabaseSubscriptionError("snapshot_order_invalid");
         previous = document;
         return Object.freeze({ document, point: pointCopy(row.point, this.binding.scope) });
@@ -293,7 +293,7 @@ export class DatabaseSubscriptionView {
       /** @type {Set<string>} */
       const documents = new Set();
       for (const effect of group.effects) {
-        const document = requireDatabaseUuid(effect.document, "document");
+        const document = requireDatabaseId(effect.document, "document");
         if (documents.has(document)) throw new DatabaseSubscriptionError("duplicate_group_document");
         documents.add(document);
         if (effect.point === null) rows.delete(document);

package/src/http.js

@@ -1,10 +1,7 @@
 import { resolveAccessToken, resolveTsAuthRuntimeConfig } from "./config.js";
 import { err, ok, sanitizeDiagnostic } from "./result.js";
-import {
-  regionalIssuerOrigin,
-  TsAuthEndpointDiscovery,
-} from "./ts-auth-discovery.js";
 import { parseDatabaseJson } from "./database-codec.js";
+import { validateTsAuthIds } from "./ts-auth-ids.js";
 /** @import { ResolvedTsAuthRuntimeConfig, TsAuthRuntimeConfig, FetchLike } from "./config.js" */
 /** @import { TerraScaleError, TerraScaleErrorCategory, TerraScaleResult, TerraScaleValidationIssue } from "./result.js" */
 
@@ -21,7 +18,6 @@ import { parseDatabaseJson } from "./database-codec.js";
  *   readonly formBody?: URLSearchParams | string | undefined;
  *   readonly userinfoAccessToken?: string | undefined;
  *   readonly resourceIntrospectionBasic?: string | undefined;
- *   readonly issuer?: string | undefined; // Behind the Atlas proxy a regional issuer is called on its own host.
  *   readonly signal?: AbortSignal | undefined;
  * }} TsAuthRequest
  */
@@ -39,25 +35,14 @@ export class TsAuthHttp {
   #fetch;
   /** @readonly @type {TsAuthRuntimeConfig["accessToken"]} */
   #accessToken;
-  /** @readonly @type {TsAuthEndpointDiscovery | undefined} */
-  #discovery;
-
-  /**
-   * @param {TsAuthRuntimeConfig} config
-   * @param {{ readonly authReverseProxy?: boolean }} [options]
-   */
-  constructor(config, options) {
+  /** @param {TsAuthRuntimeConfig} config */
+  constructor(config) {
     this.config = Object.freeze(resolveTsAuthRuntimeConfig(config));
     const fetchHandler = config.fetch ?? globalThis.fetch?.bind(globalThis);
     if (fetchHandler === undefined)
       throw new TypeError("TsAuthClient requires a fetch implementation.");
     this.#fetch = fetchHandler;
     this.#accessToken = config.accessToken;
-    this.#discovery =
-      options?.authReverseProxy !== true &&
-      this.config.apiBaseUrl === "https://auth.terrascale.tech"
-        ? new TsAuthEndpointDiscovery(fetchHandler)
-        : undefined;
   }
 
   /**
@@ -89,18 +74,6 @@ export class TsAuthHttp {
         options.body !== undefined
           ? JSON.stringify(options.body)
           : options.formBody?.toString();
-      const issuerOrigin =
-        this.#discovery === undefined || options.issuer === undefined
-          ? undefined
-          : regionalIssuerOrigin(options.issuer);
-      const endpoints =
-        issuerOrigin === undefined
-          ? await withCancellation(
-              this.#discovery?.endpoints(signal) ?? Promise.resolve(undefined),
-              signal,
-            )
-          : [issuerOrigin];
-      let endpointIndex = 0;
       let attempt = 0;
       let refreshed = false;
       /** @type {string | undefined} */
@@ -162,7 +135,7 @@ export class TsAuthHttp {
             );
           const request = new Request(
             buildUrl(
-              endpoints?.[endpointIndex] ?? this.config.apiBaseUrl,
+              this.config.apiBaseUrl,
               options.path,
               options.query,
             ),
@@ -188,16 +161,6 @@ export class TsAuthHttp {
             signal.throwIfAborted();
           }
           responseReceived = true;
-          if (
-            options.method === "GET" &&
-            endpoints !== undefined &&
-            endpointIndex < endpoints.length - 1 &&
-            [502, 503, 504].includes(response.status)
-          ) {
-            void response.body?.cancel().catch(() => undefined);
-            endpointIndex += 1;
-            continue;
-          }
           if (
             response.type === "opaqueredirect" ||
             (response.status >= 300 && response.status < 400)
@@ -227,6 +190,15 @@ export class TsAuthHttp {
                 response.status,
                 response.headers,
               );
+            try {
+              validateTsAuthIds(parsed.value, options.routeName);
+            } catch {
+              return err(options.routeName, {
+                kind: "invalid-response", code: "invalid_response",
+                message: "ts-auth returned a noncanonical entity ID.", status: response.status,
+                requestId: requestIdFrom(response.headers),
+              }, response.status, response.headers);
+            }
             return ok(
               options.routeName,
               response.status,
@@ -283,13 +255,6 @@ export class TsAuthHttp {
             !signal?.aborted &&
             options.method === "GET"
           ) {
-            if (
-              endpoints !== undefined &&
-              endpointIndex < endpoints.length - 1
-            ) {
-              endpointIndex += 1;
-              continue;
-            }
             if (attempt < this.config.maxRetryAttempts) {
               await delayForRetry(
                 retryDelay(undefined, this.config.retryDelayMs, attempt),

package/src/ids.js

@@ -0,0 +1,22 @@
+import { isValid, monotonicFactory } from "ulid";
+
+/** A plain 26-character, uppercase Crockford ULID. @typedef {string} EntityId */
+
+const nextId = monotonicFactory();
+
+/** @returns {EntityId} Monotonic within a millisecond, including clock rollback. */
+export function generateId() {
+  return nextId();
+}
+
+/** @param {unknown} value @returns {value is EntityId} */
+export function isValidId(value) {
+  // The library also accepts lowercase and 130-bit overflow; the public contract does not.
+  return typeof value === "string" && isValid(value) && value === value.toUpperCase() && /^[0-7]/u.test(value);
+}
+
+/** @param {unknown} value @param {string} [name] @returns {EntityId} */
+export function requireId(value, name = "Entity ID") {
+  if (!isValidId(value)) throw new TypeError(`${name} must be a plain 26-character canonical uppercase Crockford ULID.`);
+  return value;
+}

package/src/index.js

@@ -1,6 +1,6 @@
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
-// TerraBase v1: name-based documents, transactions, queries and shapes.
+// Project-scoped TerraBase API; shape support is retained for the historical release.
 export {
   createTerraBaseV1Client,
   TerraBaseV1Client,
@@ -19,7 +19,12 @@ export {
   isTerraBaseV1Error,
 } from "./v1/errors.js";
 export { v1Filter } from "./v1/filter.js";
-export { documentIdFor } from "./v1/ids.js";
+export { V1ShapeSubscription } from "./v1/shape-subscription.js";
+/** @typedef {import("./v1/shape-subscription.js").V1ShapeSubscribeOptions} V1ShapeSubscribeOptions */
+/** @typedef {import("./v1/shape-subscription.js").V1ShapeDocument} V1ShapeDocument */
+/** @typedef {import("./v1/shape-reader.js").V1SealedShapePosition} V1SealedShapePosition */
+export { generateId, isValidId, requireId } from "./ids.js";
+/** @typedef {import("./ids.js").EntityId} EntityId */
 export { ExactDecimal } from "./v1/json.js";
 
 /** @typedef {import("./v1/transport.js").TerraBaseV1ClientConfig} TerraBaseV1ClientConfig */
@@ -53,6 +58,11 @@ export { ExactDecimal } from "./v1/json.js";
 /** @typedef {import("./v1/shapes.js").V1ShapeOp} V1ShapeOp */
 
 export { staticBaseUrlResolver } from "./v1/transport.js";
+export { V1Databases } from "./v1/catalog.js";
+export { V1SavedQueries } from "./v1/saved-queries.js";
+/** @typedef {import("./v1/saved-queries.js").V1SavedQuery} V1SavedQuery */
+/** @typedef {import("./v1/saved-queries.js").V1SavedQueryRequest} V1SavedQueryRequest */
+/** @typedef {import("./v1/saved-queries.js").V1SavedQueryPage} V1SavedQueryPage */
 /** @typedef {import("./v1/transport.js").TerraBaseV1ClientConfig} TerraBaseClientConfig */
 /** @typedef {import("./v1/transport.js").V1EndpointContext} V1EndpointContext */
 /** @typedef {import("./v1/transport.js").V1EndpointResolver} V1EndpointResolver */
@@ -60,3 +70,68 @@ export { staticBaseUrlResolver } from "./v1/transport.js";
 /** @typedef {import("./v1/terrabase-v1.js").V1CollectionPage} V1CollectionPage */
 /** @typedef {import("./v1/terrabase-v1.js").V1CollectionListOptions} V1CollectionListOptions */
 /** @typedef {import("./v1/shapes.js").V1ShapePage} V1ShapePage */
+/** @typedef {import("./v1/sql.js").V1SqlRow} V1SqlRow */
+/** @typedef {import("./v1/sql.js").V1SqlResult} V1SqlResult */
+/** @typedef {import("./v1/sql.js").V1SqlIndexSuggestion} V1SqlIndexSuggestion */
+/** @typedef {import("./v1/sql.js").V1SqlCheck} V1SqlCheck */
+/** @typedef {import("./v1/changes.js").V1ChangeStreamRequest} V1ChangeStreamRequest */
+/** @typedef {import("./v1/changes.js").V1DatabaseChange} V1DatabaseChange */
+/** @typedef {import("./v1/changes.js").V1DatabaseChangeCursor} V1DatabaseChangeCursor */
+/** @typedef {import("./v1/catalog.js").V1ManagedDatabase} V1ManagedDatabase */
+/** @typedef {import("./v1/catalog.js").V1DatabaseCreateRequest} V1DatabaseCreateRequest */
+/** @typedef {import("./v1/catalog.js").V1DatabaseUpdateRequest} V1DatabaseUpdateRequest */
+/** @typedef {import("./v1/catalog.js").V1DatabaseBranchRequest} V1DatabaseBranchRequest */
+/** @typedef {import("./v1/catalog.js").V1DatabaseListRequest} V1DatabaseListRequest */
+/** @typedef {import("./v1/catalog.js").V1DatabasePage} V1DatabasePage */
+/** @typedef {import("./v1/catalog.js").V1CollectionSchema} V1CollectionSchema */
+
+export { V1DatabaseSchemaClient } from "./v1/database-schema.js";
+/** @typedef {import("./v1/database-schema.js").V1InferredSchema} V1InferredSchema */
+/** @typedef {import("./v1/database-schema.js").V1DatabaseSchema} V1DatabaseSchema */
+/** @typedef {import("./v1/database-schema.js").V1UniqueSchema} V1UniqueSchema */
+/** @typedef {import("./v1/database-schema.js").V1UniqueSchemaRequest} V1UniqueSchemaRequest */
+/** @typedef {import("./v1/database-schema.js").V1QueryShapes} V1QueryShapes */
+
+export { V1Indexes } from "./v1/indexes.js";
+/** @typedef {import("./v1/indexes.js").V1Index} V1Index */
+/** @typedef {import("./v1/indexes.js").V1IndexList} V1IndexList */
+/** @typedef {import("./v1/indexes.js").V1AutoIndexPolicy} V1AutoIndexPolicy */
+/** @typedef {import("./v1/indexes.js").V1IndexRecommendations} V1IndexRecommendations */
+/** @typedef {import("./v1/indexes.js").V1AppliedIndexRecommendation} V1AppliedIndexRecommendation */
+/** @typedef {import("./v1/indexes.js").V1CreateIndexRequest} V1CreateIndexRequest */
+
+export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
+/** @typedef {import("./v1/usage.js").V1DatabaseUsage} V1DatabaseUsage */
+/** @typedef {import("./v1/usage.js").V1ProjectUsage} V1ProjectUsage */
+/** @typedef {import("./v1/usage.js").V1Analytics} V1Analytics */
+/** @typedef {import("./v1/usage.js").V1Replication} V1Replication */
+/** @typedef {import("./v1/usage.js").V1UsageRequest} V1UsageRequest */
+/** @typedef {import("./v1/usage.js").V1AnalyticsRequest} V1AnalyticsRequest */
+
+export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";
+/** @typedef {import("./v1/backups.js").V1Backup} V1Backup */
+/** @typedef {import("./v1/backups.js").V1BackupPage} V1BackupPage */
+/** @typedef {import("./v1/backups.js").V1BackupPolicy} V1BackupPolicy */
+/** @typedef {import("./v1/backups.js").V1RestoreWindow} V1RestoreWindow */
+/** @typedef {import("./v1/backups.js").V1PointInTimePlan} V1PointInTimePlan */
+/** @typedef {import("./v1/backups.js").V1RestoredDatabase} V1RestoredDatabase */
+/** @typedef {import("./v1/backups.js").V1BackupDestination} V1BackupDestination */
+/** @typedef {import("./v1/backups.js").V1BackupPolicyRequest} V1BackupPolicyRequest */
+/** @typedef {import("./v1/backups.js").V1PointInTimeRequest} V1PointInTimeRequest */
+/** @typedef {import("./v1/backups.js").V1PointInTimeRestoreRequest} V1PointInTimeRestoreRequest */
+/** @typedef {import("./v1/backups.js").V1BackupDestinationRequest} V1BackupDestinationRequest */
+
+export { V1Imports } from "./v1/imports.js";
+/** @typedef {import("./v1/imports.js").V1ImportJob} V1ImportJob */
+/** @typedef {import("./v1/imports.js").V1ImportOptions} V1ImportOptions */
+/** @typedef {import("./v1/imports.js").V1CreateImportRequest} V1CreateImportRequest */
+
+export { createTerraBaseSystemClient, V1Health, V1Platform } from "./v1/system.js";
+/** @typedef {import("./v1/system.js").TerraBaseSystemClientConfig} TerraBaseSystemClientConfig */
+/** @typedef {import("./v1/system.js").V1ProbeStatus} V1ProbeStatus */
+/** @typedef {import("./v1/system.js").V1ReplicationHealth} V1ReplicationHealth */
+/** @typedef {import("./v1/system.js").V1PlatformDatabases} V1PlatformDatabases */
+/** @typedef {import("./v1/shape-manifest.js").V1ShapeManifest} V1ShapeManifest */
+/** @typedef {import("./v1/shape-manifest.js").V1ShapeManifestRequest} V1ShapeManifestRequest */
+/** @typedef {import("./v1/shape-reader.js").V1ShapeKeyRequest} V1ShapeKeyRequest */
+/** @typedef {import("./v1/shape-reader.js").V1ShapeKey} V1ShapeKey */

package/src/local/better-auth.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { generateId, requireId } from "../ids.js";
 import { createAdapterFactory } from "@better-auth/core/db/adapter";
 /** @import { CleanedWhere, CustomAdapter, DBAdapter, JoinConfig } from "@better-auth/core/db/adapter" */
 /** @import { BetterAuthOptions } from "@better-auth/core" */
@@ -29,6 +29,8 @@ export function createLocalBetterAuthAdapter(store) {
    * @returns {DBAdapter<BetterAuthOptions>}
    */
   function make(options, scoped) {
+    if (options.advanced?.database?.generateId === "uuid")
+      throw new TypeError("Better Auth entity IDs must be ULIDs; UUID generation is unavailable.");
     /** @type {ReturnType<typeof createAdapterFactory<BetterAuthOptions>>} */
     const factory = createAdapterFactory({
       config: {
@@ -38,7 +40,7 @@ export function createLocalBetterAuthAdapter(store) {
         supportsArrays: true,
         supportsBooleans: true,
         supportsNumericIds: false,
-        supportsUUIDs: true,
+        customIdGenerator: generateId,
         transaction: async (callback) => {
           if (scoped)
             throw new Error("Nested local auth transactions are unavailable.");
@@ -65,7 +67,8 @@ function customAdapter(store, config, scoped) {
    * @param {string} model
    * @returns {Row[]}
    */
-  const rows = (model) => store.list("local-auth", model);
+  const rows = (model) => store.listEntries("local-auth", model)
+    .map(entry => ({ .../** @type {Row} */ (entry.value), id: requireId(entry.id) }));
   /**
    * @param {string} model
    * @param {readonly CleanedWhere[]} clauses
@@ -150,13 +153,21 @@ function customAdapter(store, config, scoped) {
    */
   const save = (model, input, creating = false) => {
     const row = jsonRow(input);
-    const id =
-      typeof row.id === "string" && row.id.length > 0 ? row.id : randomUUID();
+    const id = row.id === undefined ? generateId() : requireId(row.id);
+    for (const [logical, table] of Object.entries(config.schema)) {
+      if (config.getModelName(logical) !== model) continue;
+      for (const [field, schema] of Object.entries(table.fields)) {
+        if (schema.references?.field !== "id") continue;
+        const value = row[config.getFieldName({ model: logical, field })];
+        if (value !== undefined && value !== null) requireId(value, field);
+      }
+    }
     const candidate = { ...row, id };
     if (creating && store.get("local-auth", model, id) !== undefined)
       throw new LocalAuthConstraintError();
     ensureUnique(model, candidate);
-    store.put("local-auth", model, id, candidate);
+    delete row.id;
+    store.put("local-auth", model, id, row);
     return candidate;
   };
   /**

package/src/local/environment.js

@@ -14,7 +14,6 @@ export const localSqlitePresenceIndicators = /** @type {const} */ ([
   "NETLIFY",
   "CF_PAGES",
   "RENDER",
-  "FLY_APP_NAME",
   "K_SERVICE",
   "CLOUD_RUN_JOB",
   "KUBERNETES_SERVICE_HOST",

package/src/local/index.js

@@ -1,5 +1,5 @@
+import { generateId } from "../ids.js";
 import { isAbsolute } from "node:path";
-import { randomUUID } from "node:crypto";
 import { createTerraBaseClient } from "./legacy-client.js";
 import { normalizeLocalBearerToken } from "./authentication.js";
 import { assertLocalSqliteEnvironment } from "./environment.js";
@@ -86,7 +86,7 @@ export class TerraScaleSqliteRuntime {
       const scope =
         options.scope ??
         (stored === undefined
-          ? { tenant: randomUUID(), database: randomUUID(), shard: 0n }
+          ? { tenant: generateId(), database: generateId(), shard: 0n }
           : { ...stored, shard: BigInt(stored.shard) });
       this.#router = new TerraScaleLocalRouter(this.#store, scope, {
         authentication,

package/src/local/legacy-client.js

@@ -2,7 +2,7 @@
 import {
   decodeDatabaseCommitReceipt, decodeDatabasePoint, decodeDatabaseQueryPage,
   decodeDatabaseSubscription, decodeDatabaseStatus, encodeDatabaseStatus, encodeDatabaseCommit, encodeDatabaseQuery,
-  encodeDatabaseSubscription, encodeDatabaseAuthority, parseDatabaseJson, requireDatabaseU64, requireDatabaseUuid,
+  encodeDatabaseSubscription, encodeDatabaseAuthority, parseDatabaseJson, requireDatabaseU64, requireDatabaseId,
 } from "../database-codec.js";
 /**
  * @import {
@@ -61,7 +61,7 @@ function identityAuthority(authority) {
  * @returns {string}
  */
 function scopePath(scope) {
-  return `/v1/tenants/${requireDatabaseUuid(scope.tenant, "tenant")}/databases/${requireDatabaseUuid(scope.database, "database")}/shards/${requireDatabaseU64(scope.shard, "shard")}`;
+  return `/v1/tenants/${requireDatabaseId(scope.tenant, "tenant")}/databases/${requireDatabaseId(scope.database, "database")}/shards/${requireDatabaseU64(scope.shard, "shard")}`;
 }
 
 /**
@@ -195,7 +195,7 @@ export class TerraBaseClient {
 
   /** @param {TerraBaseClientConfig} config */
   constructor(config) {
-    this.#scope = Object.freeze({ tenant: requireDatabaseUuid(config.tenant, "tenant"), database: requireDatabaseUuid(config.database, "database"), shard: requireDatabaseU64(config.shard, "shard") });
+    this.#scope = Object.freeze({ tenant: requireDatabaseId(config.tenant, "tenant"), database: requireDatabaseId(config.database, "database"), shard: requireDatabaseU64(config.shard, "shard") });
     this.#config = { ...config };
     this.#fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.#path = scopePath(this.#scope);
@@ -214,7 +214,7 @@ export class TerraBaseClient {
    * @returns {Promise<DatabaseResult<DatabasePoint>>}
    */
   read(collection, document, options = {}) {
-    const path = `${this.#collectionPath(collection)}/documents/${requireDatabaseUuid(document, "document")}`;
+    const path = `${this.#collectionPath(collection)}/documents/${requireDatabaseId(document, "document")}`;
     return this.#request(path, "GET", undefined, raw => this.#scopedPoint(decodeDatabasePoint(raw)), options);
   }
 
@@ -312,7 +312,7 @@ export class TerraBaseClient {
    * @param {string} collection
    * @returns {string}
    */
-  #collectionPath(collection) { return `${this.#path}/collections/${requireDatabaseUuid(collection, "collection")}`; }
+  #collectionPath(collection) { return `${this.#path}/collections/${requireDatabaseId(collection, "collection")}`; }
 
   /**
    * @param {DatabasePoint} point