terrascale 0.3.0

package/types/discovery.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Parse only the current closed native8 descriptor, without widening its lease or capabilities.
+ * @param {unknown} payload
+ * @param {DatabaseScope} expected
+ * @param {number} [nowMs]
+ * @returns {TerraBaseRoutingDocument}
+ */
+export function parseTerraBaseRoutingDocument(payload: unknown, expected: DatabaseScope, nowMs?: number): TerraBaseRoutingDocument;
+/** @import { FetchLike } from "./config.js" */
+/** @import { DatabaseScope } from "./database-types.js" */
+/** Frozen authenticated native receiver; no alternate metadata origin is admitted. */
+export const terraBaseDiscoveryOrigin: "https://atlas.terrascale.tech";
+/** @typedef {typeof capabilityNames[number]} TerraBaseRoutingCapability */
+/** @typedef {Readonly<Record<TerraBaseRoutingCapability, boolean>>} TerraBaseRoutingCapabilities */
+/**
+ * @typedef {{
+ *   readonly region: string;
+ *   readonly url: string;
+ *   readonly priority: number;
+ *   readonly catalog: { readonly digest: string };
+ *   readonly capabilities: TerraBaseRoutingCapabilities;
+ *   readonly security_writer: null;
+ * }} TerraBaseRoutingEndpoint
+ */
+/**
+ * @typedef {{
+ *   readonly schema_version: 1;
+ *   readonly scope: DatabaseScope;
+ *   readonly authority: {
+ *     readonly deployment_id: string;
+ *     readonly cell: string;
+ *     readonly publisher_id: string;
+ *     readonly publisher_generation: bigint;
+ *   };
+ *   readonly revision: bigint;
+ *   readonly published_at: number;
+ *   readonly expires_at: number;
+ *   readonly refreshSeconds: number;
+ *   readonly residency: readonly string[] | null;
+ *   readonly endpoints: readonly TerraBaseRoutingEndpoint[];
+ * }} TerraBaseRoutingDocument
+ */
+export class TerraBaseDiscoveryError extends Error {
+    /**
+     * @param {string} code
+     * @param {number} [status]
+     */
+    constructor(code: string, status?: number);
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly code: string;
+    /**
+     * @readonly
+     * @type {number | undefined}
+     */
+    readonly status: number | undefined;
+}
+/** Per-scope observation floors survive lease expiry and credential rotation for this client. */
+export class TerraBaseDiscoveryRouter {
+    /**
+     * @param {DatabaseScope} scope
+     * @param {FetchLike} [fetch]
+     * @param {number} [timeoutMs]
+     */
+    constructor(scope: DatabaseScope, fetch?: FetchLike, timeoutMs?: number);
+    /**
+     * @param {string} apiKey
+     * @param {readonly TerraBaseRoutingCapability[]} required
+     * @param {AbortSignal} [callerSignal]
+     * @returns {Promise<TerraBaseRoutingEndpoint>}
+     */
+    resolve(apiKey: string, required: readonly TerraBaseRoutingCapability[], callerSignal?: AbortSignal): Promise<TerraBaseRoutingEndpoint>;
+    /**
+     * Recheck immediately before native dispatch, including concurrently advanced floors.
+     * @param {TerraBaseRoutingEndpoint} endpoint
+     * @returns {void}
+     */
+    assertCurrent(endpoint: TerraBaseRoutingEndpoint): void;
+    #private;
+}
+export type TerraBaseRoutingCapability = (typeof capabilityNames)[number];
+export type TerraBaseRoutingCapabilities = Readonly<Record<TerraBaseRoutingCapability, boolean>>;
+export type TerraBaseRoutingEndpoint = {
+    readonly region: string;
+    readonly url: string;
+    readonly priority: number;
+    readonly catalog: {
+        readonly digest: string;
+    };
+    readonly capabilities: TerraBaseRoutingCapabilities;
+    readonly security_writer: null;
+};
+export type TerraBaseRoutingDocument = {
+    readonly schema_version: 1;
+    readonly scope: DatabaseScope;
+    readonly authority: {
+        readonly deployment_id: string;
+        readonly cell: string;
+        readonly publisher_id: string;
+        readonly publisher_generation: bigint;
+    };
+    readonly revision: bigint;
+    readonly published_at: number;
+    readonly expires_at: number;
+    readonly refreshSeconds: number;
+    readonly residency: readonly string[] | null;
+    readonly endpoints: readonly TerraBaseRoutingEndpoint[];
+};
+import type { DatabaseScope } from "./database-types.js";
+import type { FetchLike } from "./config.js";
+declare const capabilityNames: readonly ["client_v1", "read", "query", "subscriptions", "write", "conditional_mutation", "atomic_groups", "security_state"];
+export {};

package/types/http.d.ts

@@ -0,0 +1,46 @@
+/** Private transport for the named hosted identity and OIDC operations. */
+export class TsAuthHttp {
+    /**
+     * @param {TsAuthRuntimeConfig} config
+     * @param {{ readonly authReverseProxy?: boolean }} [options]
+     */
+    constructor(config: TsAuthRuntimeConfig, options?: {
+        readonly authReverseProxy?: boolean;
+    });
+    /**
+     * @readonly
+     * @type {ResolvedTsAuthRuntimeConfig}
+     */
+    readonly config: ResolvedTsAuthRuntimeConfig;
+    /**
+     * @template TResponse
+     * @template [TBody=unknown]
+     * @param {TsAuthRequest<TBody>} options
+     * @returns {Promise<TerraScaleResult<TResponse>>}
+     */
+    request<TResponse, TBody = unknown>(options: TsAuthRequest<TBody>): Promise<TerraScaleResult<TResponse>>;
+    #private;
+}
+export type ParsedBody = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly errorMessage: string;
+};
+export type TsAuthRouteName = `tsauth.${string}`;
+export type TsAuthHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+export type TsAuthRequest<TBody> = {
+    readonly method: TsAuthHttpMethod;
+    readonly path: string;
+    readonly routeName: TsAuthRouteName;
+    readonly query?: object | undefined;
+    readonly body?: TBody | undefined;
+    readonly formBody?: URLSearchParams | string | undefined;
+    readonly userinfoAccessToken?: string | undefined;
+    readonly resourceIntrospectionBasic?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+};
+import type { ResolvedTsAuthRuntimeConfig } from "./config.js";
+import type { TerraScaleResult } from "./result.js";
+import type { TsAuthRuntimeConfig } from "./config.js";

package/types/index.d.ts

@@ -0,0 +1,52 @@
+export * from "./schema.js";
+export * from "./sql.js";
+export type TerraBaseClientConfig = import("./database.js").TerraBaseClientConfig;
+export type PreparedDatabaseCommit = import("./database.js").PreparedDatabaseCommit;
+export type DatabaseRequestOptions = import("./database.js").DatabaseRequestOptions;
+export type CanonicalUuid = import("./database-types.js").CanonicalUuid;
+export type DatabaseScope = import("./database-types.js").DatabaseScope;
+export type CollectionBinding = import("./database-types.js").CollectionBinding;
+export type DatabaseValue = import("./database-types.js").DatabaseValue;
+export type DatabaseField = import("./database-types.js").DatabaseField;
+export type DatabaseObserved = import("./database-types.js").DatabaseObserved;
+export type DatabaseEvent = import("./database-types.js").DatabaseEvent;
+export type DatabaseAuthority = import("./database-types.js").DatabaseAuthority;
+export type DatabaseCondition = import("./database-types.js").DatabaseCondition;
+export type DatabaseWriteValue = import("./database-types.js").DatabaseWriteValue;
+export type DatabaseWrite = import("./database-types.js").DatabaseWrite;
+export type DatabaseTransactionId = import("./database-types.js").DatabaseTransactionId;
+export type DatabaseCommit = import("./database-types.js").DatabaseCommit;
+export type DatabaseSibling = import("./database-types.js").DatabaseSibling;
+export type DatabasePoint = import("./database-types.js").DatabasePoint;
+export type DatabaseQueryValue = import("./database-types.js").DatabaseQueryValue;
+export type DatabaseQueryPredicate = import("./database-types.js").DatabaseQueryPredicate;
+export type DatabaseQuery = import("./database-types.js").DatabaseQuery;
+export type DatabaseQueryRow = import("./database-types.js").DatabaseQueryRow;
+export type DatabaseQueryPage = import("./database-types.js").DatabaseQueryPage;
+export type DatabaseCommitReceipt = import("./database-types.js").DatabaseCommitReceipt;
+export type DatabaseTransactionIdentity = import("./database-types.js").DatabaseTransactionIdentity;
+export type DatabaseTransactionStatus = import("./database-types.js").DatabaseTransactionStatus;
+export type DatabaseResult<T> = import("./database-types.js").DatabaseResult<T>;
+export type DatabaseSubscriptionRequest = import("./database-types.js").DatabaseSubscriptionRequest;
+export type DatabaseSubscriptionEffect = import("./database-types.js").DatabaseSubscriptionEffect;
+export type DatabaseSubscriptionGroup = import("./database-types.js").DatabaseSubscriptionGroup;
+export type DatabaseSubscriptionResponse = import("./database-types.js").DatabaseSubscriptionResponse;
+export type TerraBaseRoutingCapability = import("./discovery.js").TerraBaseRoutingCapability;
+export type TerraBaseRoutingCapabilities = import("./discovery.js").TerraBaseRoutingCapabilities;
+export type TerraBaseRoutingEndpoint = import("./discovery.js").TerraBaseRoutingEndpoint;
+export type TerraBaseRoutingDocument = import("./discovery.js").TerraBaseRoutingDocument;
+export type TerraScaleBlockedCapability = import("./management-contracts.js").TerraScaleBlockedCapability;
+export type TerraScaleResult<TValue> = import("./result.js").TerraScaleResult<TValue>;
+export type TerraScaleError = import("./result.js").TerraScaleError;
+export type TerraScaleFailure = import("./result.js").TerraScaleFailure;
+export type TerraScaleSuccess<TValue> = import("./result.js").TerraScaleSuccess<TValue>;
+export type DatabaseQueryOptions = import("./database-view.js").DatabaseQueryOptions;
+export type DatabaseViewBinding = import("./database-view.js").DatabaseViewBinding;
+export type DatabaseViewPosition = import("./database-view.js").DatabaseViewPosition;
+export type DatabaseViewSnapshot = import("./database-view.js").DatabaseViewSnapshot;
+export type DatabaseQueryCallbacks = import("./database-view.js").DatabaseQueryCallbacks;
+export type DatabaseQuerySource = import("./database-view.js").DatabaseQuerySource;
+export { createTerraBaseClient, TerraBaseClient } from "./database.js";
+export { terraBaseDiscoveryOrigin, parseTerraBaseRoutingDocument, TerraBaseDiscoveryError, TerraBaseDiscoveryRouter } from "./discovery.js";
+export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
+export { createDatabaseQuery, DatabaseSubscriptionView, DatabaseSubscriptionError } from "./database-view.js";

package/types/local/authentication.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeLocalBearerToken(value: unknown): string;
+/**
+ * @param {string | null} authorization
+ * @param {string} expectedToken
+ * @returns {boolean}
+ */
+export function matchesLocalBearerAuthorization(authorization: string | null, expectedToken: string): boolean;

package/types/local/better-auth.d.ts

@@ -0,0 +1,33 @@
+/** @import { CleanedWhere, CustomAdapter, DBAdapter, JoinConfig } from "@better-auth/core/db/adapter" */
+/** @import { BetterAuthOptions } from "@better-auth/core" */
+/** @import { TerraScaleSqliteStore } from "./store.js" */
+/** @typedef {Record<string, unknown>} Row */
+/**
+ * @typedef {Parameters<
+ *   NonNullable<Parameters<typeof createAdapterFactory>[0]["adapter"]>
+ * >[0]} FactoryConfig
+ */
+/**
+ * @typedef {(
+ *   options: BetterAuthOptions,
+ * ) => DBAdapter<BetterAuthOptions>} LocalBetterAuthAdapterFactory
+ */
+/**
+ * Better Auth 1.7.2 over explicitly enabled development SQLite only.
+ *
+ * @param {TerraScaleSqliteStore} store
+ * @returns {LocalBetterAuthAdapterFactory}
+ */
+export function createLocalBetterAuthAdapter(store: TerraScaleSqliteStore): LocalBetterAuthAdapterFactory;
+export class LocalAuthConstraintError extends Error {
+    constructor();
+    /** @readonly */
+    readonly code: "unique_conflict";
+}
+export type Row = Record<string, unknown>;
+export type FactoryConfig = Parameters<NonNullable<Parameters<typeof createAdapterFactory>[0]["adapter"]>>[0];
+export type LocalBetterAuthAdapterFactory = (options: BetterAuthOptions) => DBAdapter<BetterAuthOptions>;
+import type { TerraScaleSqliteStore } from "./store.js";
+import { createAdapterFactory } from "@better-auth/core/db/adapter";
+import type { BetterAuthOptions } from "@better-auth/core";
+import type { DBAdapter } from "@better-auth/core/db/adapter";

package/types/local/cli.d.ts

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

package/types/local/context.d.ts

@@ -0,0 +1,14 @@
+/** @typedef {"permissive" | "required"} LocalAuthenticationMode */
+/**
+ * @param {unknown} value
+ * @param {number} [status]
+ * @returns {Response}
+ */
+export function jsonResponse(value: unknown, status?: number): Response;
+/**
+ * @param {number} status
+ * @param {string} code
+ * @returns {Response}
+ */
+export function problemResponse(status: number, code: string): Response;
+export type LocalAuthenticationMode = "permissive" | "required";

package/types/local/environment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @param {Readonly<Record<string, string | undefined>>} [environment]
+ * @returns {void}
+ */
+export function assertLocalSqliteEnvironment(environment?: Readonly<Record<string, string | undefined>>): void;
+export const localSqlitePresenceIndicators: readonly ["CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "FORGEJO_ACTIONS", "GITEA_ACTIONS", "TF_BUILD", "BUILDKITE", "CIRCLECI", "JENKINS_URL", "TEAMCITY_VERSION", "VERCEL", "NETLIFY", "CF_PAGES", "RENDER", "FLY_APP_NAME", "K_SERVICE", "CLOUD_RUN_JOB", "KUBERNETES_SERVICE_HOST", "AWS_LAMBDA_FUNCTION_NAME", "AWS_EXECUTION_ENV", "ECS_CONTAINER_METADATA_URI", "ECS_CONTAINER_METADATA_URI_V4", "WEBSITE_INSTANCE_ID", "WEBSITE_SITE_NAME", "FUNCTIONS_WORKER_RUNTIME", "DYNO", "HEROKU_APP_NAME", "RAILWAY_ENVIRONMENT", "RAILWAY_SERVICE_ID", "NOMAD_ALLOC_ID", "TERRASCALE_DEPLOYMENT", "TERRASCALE_QUALIFICATION"];
+/**
+ * Explicit opt-in for a hosted development environment.
+ *
+ * Hosting platforms set a presence indicator on every workload, including
+ * development environments, so the SDK cannot tell a hosted dev environment
+ * from production by presence alone. Setting this variable to a true value
+ * relaxes *platform* indicators only: CI, qualification, and every stage
+ * indicator (`NODE_ENV=production`, `STAGE=staging`, …) still refuse.
+ */
+export const localSqliteHostedOptIn: "TERRASCALE_LOCAL_SQLITE_ALLOW_HOSTED";
+/**
+ * Presence indicators the opt-in never relaxes.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const localSqliteUnrelaxableIndicators: ReadonlySet<string>;
+export const localSqliteStageIndicators: readonly ["NODE_ENV", "APP_ENV", "ENVIRONMENT", "STAGE", "DEPLOY_ENV", "DEPLOYMENT_ENVIRONMENT", "TERRASCALE_ENV", "TERRASCALE_ENVIRONMENT", "VERCEL_ENV"];

package/types/local/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @param {TerraScaleSqliteRuntimeOptions} options
+ * @returns {TerraScaleSqliteRuntime}
+ */
+export function createTerraScaleSqliteRuntime(options: TerraScaleSqliteRuntimeOptions): TerraScaleSqliteRuntime;
+/** @import { TerraBaseClient, TerraBaseClientConfig } from "../database.js" */
+/** @import { CollectionBinding, DatabaseScope } from "../database-types.js" */
+/** @typedef {import("./context.js").LocalAuthenticationMode} LocalAuthenticationMode */
+/** @typedef {import("./server.js").LocalServerAddress} LocalServerAddress */
+/** @typedef {import("./better-auth.js").LocalBetterAuthAdapterFactory} LocalBetterAuthAdapterFactory */
+/**
+ * @typedef {{
+ *   readonly sqlite: { readonly enabled: true; readonly databasePath: string };
+ *   readonly scope?: DatabaseScope;
+ *   readonly authentication?: LocalAuthenticationMode;
+ *   readonly bearerToken?: string;
+ *   readonly allowRemote?: boolean;
+ * }} TerraScaleSqliteRuntimeOptions
+ */
+/**
+ * @typedef {{
+ *   readonly host?: string;
+ *   readonly port?: number;
+ * }} TerraScaleLocalListenOptions
+ */
+/** Explicit Node development backend. Never load this entrypoint in deployment or qualification. */
+export class TerraScaleSqliteRuntime {
+    /**
+     * @param {TerraScaleSqliteRuntimeOptions} options
+     */
+    constructor(options: TerraScaleSqliteRuntimeOptions);
+    /**
+     * @readonly
+     * @type {DatabaseScope}
+     */
+    readonly scope: DatabaseScope;
+    /** @returns {string} */
+    get databasePath(): string;
+    /** @returns {LocalServerAddress | undefined} */
+    get address(): LocalServerAddress | undefined;
+    get authority(): Readonly<{
+        mode: "single_writer";
+        generation: 1n;
+        writer: {
+            readonly replica: string;
+            readonly incarnation: string;
+        };
+    }>;
+    /**
+     * @param {CollectionBinding} binding
+     * @returns {Promise<void>}
+     */
+    bindCollection(binding: CollectionBinding): Promise<void>;
+    /**
+     * @param {Pick<TerraBaseClientConfig, "requestTimeoutMs">} [options]
+     * @returns {TerraBaseClient}
+     */
+    createClient(options?: Pick<TerraBaseClientConfig, "requestTimeoutMs">): TerraBaseClient;
+    /** @returns {Promise<LocalBetterAuthAdapterFactory>} */
+    createBetterAuthAdapter(): Promise<LocalBetterAuthAdapterFactory>;
+    /**
+     * @param {TerraScaleLocalListenOptions} [options]
+     * @returns {Promise<LocalServerAddress>}
+     */
+    start(options?: TerraScaleLocalListenOptions): Promise<LocalServerAddress>;
+    /** @returns {Promise<void>} */
+    stop(): Promise<void>;
+    /** @returns {Promise<void>} */
+    reset(): Promise<void>;
+    /** @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+export type LocalAuthenticationMode = import("./context.js").LocalAuthenticationMode;
+export type LocalServerAddress = import("./server.js").LocalServerAddress;
+export type LocalBetterAuthAdapterFactory = import("./better-auth.js").LocalBetterAuthAdapterFactory;
+export type TerraScaleSqliteRuntimeOptions = {
+    readonly sqlite: {
+        readonly enabled: true;
+        readonly databasePath: string;
+    };
+    readonly scope?: DatabaseScope;
+    readonly authentication?: LocalAuthenticationMode;
+    readonly bearerToken?: string;
+    readonly allowRemote?: boolean;
+};
+export type TerraScaleLocalListenOptions = {
+    readonly host?: string;
+    readonly port?: number;
+};
+import type { DatabaseScope } from "../database-types.js";
+import type { CollectionBinding } from "../database-types.js";
+import type { TerraBaseClientConfig } from "../database.js";
+import type { TerraBaseClient } from "../database.js";

package/types/local/router.d.ts

@@ -0,0 +1,66 @@
+/** Development implementation of the admitted native grammar, never producer qualification. */
+export class TerraScaleLocalRouter {
+    /**
+     * @param {TerraScaleSqliteStore} store
+     * @param {DatabaseScope} scope
+     * @param {{
+     *   readonly authentication: LocalAuthenticationMode;
+     *   readonly bearerToken?: string;
+     * }} options
+     */
+    constructor(store: TerraScaleSqliteStore, scope: DatabaseScope, options: {
+        readonly authentication: LocalAuthenticationMode;
+        readonly bearerToken?: string;
+    });
+    get authority(): Readonly<{
+        mode: "single_writer";
+        generation: 1n;
+        writer: {
+            readonly replica: string;
+            readonly incarnation: string;
+        };
+    }>;
+    /**
+     * @param {CollectionBinding} binding
+     * @returns {void}
+     */
+    bindCollection(binding: CollectionBinding): void;
+    /**
+     * @readonly
+     * @type {FetchLike}
+     */
+    readonly fetch: FetchLike;
+    /**
+     * @param {Request} request
+     * @returns {Promise<Response>}
+     */
+    handle(request: Request): Promise<Response>;
+    #private;
+}
+export type JsonObject = Record<string, unknown>;
+export type WirePoint = JsonObject;
+export type Change = {
+    readonly sequence: string;
+    readonly entries: readonly {
+        readonly collection: string;
+        readonly document: string;
+        readonly before: WirePoint;
+        readonly after: WirePoint;
+    }[];
+};
+export type Snapshot = {
+    readonly route: string;
+    readonly predicate: string;
+    readonly limit: number;
+    readonly sequence: string;
+    readonly rows: readonly {
+        readonly document: string;
+        readonly point: WirePoint;
+    }[];
+    readonly expires: number;
+};
+import type { CollectionBinding } from "../database-types.js";
+import type { FetchLike } from "../config.js";
+import type { TerraScaleSqliteStore } from "./store.js";
+import type { DatabaseScope } from "../database-types.js";
+import type { LocalAuthenticationMode } from "./context.js";

package/types/local/server.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The local HTTP endpoint exposed by a running server.
+ *
+ * @typedef {Readonly<{
+ *   readonly origin: string;
+ *   readonly host: string;
+ *   readonly port: number;
+ * }>} LocalServerAddress
+ */
+/** @typedef {(request: Request) => Promise<Response>} LocalRequestHandler */
+/** @typedef {Readonly<{ host?: string; port?: number }>} StartOptions */
+/** @typedef {boolean | Readonly<{ allowRemote?: boolean }>} ConstructorOptions */
+/** @typedef {ReturnType<typeof createServer>} ServerLike */
+/**
+ * A small Node-only bridge for handlers that speak the Fetch API.
+ *
+ * The handler is deliberately the sole routing authority. In particular, this
+ * adapter does not reserve a health route (or any other private route).
+ */
+export class TerraScaleLocalHttpServer {
+    /**
+     * @param {LocalRequestHandler} handler
+     * @param {ConstructorOptions} [options]
+     */
+    constructor(handler: LocalRequestHandler, options?: ConstructorOptions);
+    /** @returns {LocalServerAddress | undefined} */
+    get address(): LocalServerAddress | undefined;
+    /**
+     * @param {StartOptions} [options]
+     * @returns {Promise<LocalServerAddress>}
+     */
+    start(options?: StartOptions): Promise<LocalServerAddress>;
+    /** @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+/**
+ * The local HTTP endpoint exposed by a running server.
+ */
+export type LocalServerAddress = Readonly<{
+    readonly origin: string;
+    readonly host: string;
+    readonly port: number;
+}>;
+export type LocalRequestHandler = (request: Request) => Promise<Response>;
+export type StartOptions = Readonly<{
+    host?: string;
+    port?: number;
+}>;
+export type ConstructorOptions = boolean | Readonly<{
+    allowRemote?: boolean;
+}>;
+export type ServerLike = ReturnType<typeof createServer>;
+import { createServer } from "node:http";

package/types/local/store.d.ts

@@ -0,0 +1,106 @@
+/**
+ * A small synchronous JSON record store for Node local adapters.
+ *
+ * This module intentionally imports node:sqlite and must not be used from a
+ * browser bundle. The database handle is kept private so consumers cannot
+ * bypass the store's serialization and transaction invariants.
+ */
+export class TerraScaleSqliteStore {
+    /**
+     * @param {string} databasePath
+     */
+    constructor(databasePath: string);
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly databasePath: string;
+    /** @returns {void} */
+    close(): void;
+    /** @returns {void} */
+    reset(): void;
+    /**
+     * @template T
+     * @param {string} namespace
+     * @param {string} scope
+     * @param {string} id
+     * @returns {T | undefined}
+     */
+    get<T>(namespace: string, scope: string, id: string): T | undefined;
+    /**
+     * @template T
+     * @param {string} namespace
+     * @param {string} scope
+     * @returns {T[]}
+     */
+    list<T>(namespace: string, scope: string): T[];
+    /**
+     * @template T
+     * @param {string} namespace
+     * @returns {readonly {
+     *   readonly scope: string;
+     *   readonly id: string;
+     *   readonly value: T;
+     * }[]}
+     */
+    listNamespace<T>(namespace: string): readonly {
+        readonly scope: string;
+        readonly id: string;
+        readonly value: T;
+    }[];
+    /**
+     * @template T
+     * @param {string} namespace
+     * @param {string} scope
+     * @param {string} id
+     * @param {T} value
+     * @returns {void}
+     */
+    put<T>(namespace: string, scope: string, id: string, value: T): void;
+    /**
+     * @param {string} namespace
+     * @param {string} scope
+     * @param {string} id
+     * @returns {boolean}
+     */
+    delete(namespace: string, scope: string, id: string): boolean;
+    /**
+     * @param {string} namespace
+     * @returns {void}
+     */
+    clearNamespace(namespace: string): void;
+    /**
+     * @template T
+     * @param {string} key
+     * @returns {T | undefined}
+     */
+    getMeta<T>(key: string): T | undefined;
+    /**
+     * @template T
+     * @param {string} key
+     * @param {T} value
+     * @returns {void}
+     */
+    setMeta<T>(key: string, value: T): void;
+    /**
+     * Serialize local native requests and async auth callbacks on this connection.
+     *
+     * @template T
+     * @param {() => Promise<T> | T} work
+     * @returns {Promise<T>}
+     */
+    exclusive<T>(work: () => Promise<T> | T): Promise<T>;
+    /**
+     * @template T
+     * @param {() => Promise<T>} work
+     * @returns {Promise<T>}
+     */
+    transactionAsync<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * @template T
+     * @param {() => T} work
+     * @returns {T}
+     */
+    transaction<T>(work: () => T): T;
+    #private;
+}

package/types/local/test-environment.d.ts

@@ -0,0 +1,25 @@
+/** @import { TerraScaleSqliteRuntimeOptions } from "./index.js" */
+/** @import { DatabaseCommit, DatabaseField, DatabasePoint } from "../database-types.js" */
+/**
+ * @param {Omit<TerraScaleSqliteRuntimeOptions, "sqlite">} [options]
+ */
+export function localFixture(options?: Omit<TerraScaleSqliteRuntimeOptions, "sqlite">): Promise<{
+    runtime: import("./index.js").TerraScaleSqliteRuntime;
+    client: import("../database.js").TerraBaseClient;
+    collection: `${string}-${string}-${string}-${string}-${string}`;
+    binding: {
+        collection: `${string}-${string}-${string}-${string}-${string}`;
+        schema_generation: bigint;
+        schema_digest: string;
+    };
+    directory: string;
+    databasePath: string;
+    commit: (document: string, fields: readonly DatabaseField[], point?: DatabasePoint) => DatabaseCommit;
+    close: () => Promise<void>;
+}>;
+/** Local development tests never relax CI/deployment/qualification guards. */
+export const localSqliteUnitTestsAllowed: boolean;
+import type { TerraScaleSqliteRuntimeOptions } from "./index.js";
+import type { DatabaseField } from "../database-types.js";
+import type { DatabasePoint } from "../database-types.js";
+import type { DatabaseCommit } from "../database-types.js";