terrascale 0.3.0

package/types/result.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @typedef {(
+ *   | "authentication"
+ *   | "authorization"
+ *   | "conflict"
+ *   | "domain"
+ *   | "invalid-response"
+ *   | "not-found"
+ *   | "rate-limit"
+ *   | "server"
+ *   | "transport"
+ *   | "unavailable"
+ *   | "validation"
+ * )} TerraScaleErrorKind
+ */
+/**
+ * The stable category names published by the TerraScale error envelope.
+ * @typedef {(
+ *   | "Validation"
+ *   | "Authentication"
+ *   | "Authorization"
+ *   | "NotFound"
+ *   | "Conflict"
+ *   | "RateLimit"
+ *   | "Schema"
+ *   | "Query"
+ *   | "Placement"
+ *   | "AutoFix"
+ *   | "AutoIndex"
+ *   | "Sandbox"
+ *   | "System"
+ * )} TerraScaleErrorCategory
+ */
+/**
+ * @typedef {{
+ *   readonly path?: string;
+ *   readonly message: string;
+ *   readonly code?: string;
+ * }} TerraScaleValidationIssue
+ */
+/**
+ * `fix` is optional producer-provided remediation from the published error body.
+ * `retryAfter` is the retry delay from the Retry-After header, in milliseconds,
+ * when the server sent one.
+ * @typedef {{
+ *   readonly kind: TerraScaleErrorKind;
+ *   readonly code: string;
+ *   readonly message: string;
+ *   readonly fix?: string | undefined;
+ *   readonly retryAfter?: number | undefined;
+ *   readonly category?: TerraScaleErrorCategory | undefined;
+ *   readonly detail?: string | undefined;
+ *   readonly suggestedAction?: string | undefined;
+ *   readonly docsUrl?: string | undefined;
+ *   readonly traceId?: string | undefined;
+ *   readonly status?: number | undefined;
+ *   readonly target?: string | undefined;
+ *   readonly requestId?: string | undefined;
+ *   readonly validation?: readonly TerraScaleValidationIssue[] | undefined;
+ *   readonly details?: unknown | undefined;
+ * }} TerraScaleError
+ */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly ok: true;
+ *   readonly routeName: string;
+ *   readonly status: number;
+ *   readonly headers: Headers;
+ *   readonly value: TValue;
+ * }} TerraScaleSuccess
+ */
+/**
+ * @typedef {{
+ *   readonly ok: false;
+ *   readonly routeName: string;
+ *   readonly status?: number | undefined;
+ *   readonly headers?: Headers | undefined;
+ *   readonly error: TerraScaleError;
+ *   readonly body?: unknown | undefined;
+ * }} TerraScaleFailure
+ */
+/**
+ * @template TValue
+ * @typedef {TerraScaleFailure | TerraScaleSuccess<TValue>} TerraScaleResult
+ */
+/**
+ * @template TValue
+ * @param {string} routeName
+ * @param {number} status
+ * @param {Headers} headers
+ * @param {TValue} value
+ * @returns {TerraScaleSuccess<TValue>}
+ */
+export function ok<TValue>(routeName: string, status: number, headers: Headers, value: TValue): TerraScaleSuccess<TValue>;
+/**
+ * @param {string} routeName
+ * @param {TerraScaleError} error
+ * @param {number} [status]
+ * @param {Headers} [headers]
+ * @param {unknown} [body]
+ * @returns {TerraScaleFailure}
+ */
+export function err(routeName: string, error: TerraScaleError, status?: number, headers?: Headers, body?: unknown): TerraScaleFailure;
+/**
+ * Makes values safe to retain in a public result. Error bodies and transport
+ * failures are producer-controlled and may contain credentials even when the
+ * published error contract does not. Keep this deliberately conservative:
+ * sensitive fields are replaced and secret-bearing URLs are never preserved.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function sanitizeDiagnostic(value: unknown): unknown;
+export type TerraScaleErrorKind = ("authentication" | "authorization" | "conflict" | "domain" | "invalid-response" | "not-found" | "rate-limit" | "server" | "transport" | "unavailable" | "validation");
+/**
+ * The stable category names published by the TerraScale error envelope.
+ */
+export type TerraScaleErrorCategory = ("Validation" | "Authentication" | "Authorization" | "NotFound" | "Conflict" | "RateLimit" | "Schema" | "Query" | "Placement" | "AutoFix" | "AutoIndex" | "Sandbox" | "System");
+export type TerraScaleValidationIssue = {
+    readonly path?: string;
+    readonly message: string;
+    readonly code?: string;
+};
+/**
+ * `fix` is optional producer-provided remediation from the published error body.
+ * `retryAfter` is the retry delay from the Retry-After header, in milliseconds,
+ * when the server sent one.
+ */
+export type TerraScaleError = {
+    readonly kind: TerraScaleErrorKind;
+    readonly code: string;
+    readonly message: string;
+    readonly fix?: string | undefined;
+    readonly retryAfter?: number | undefined;
+    readonly category?: TerraScaleErrorCategory | undefined;
+    readonly detail?: string | undefined;
+    readonly suggestedAction?: string | undefined;
+    readonly docsUrl?: string | undefined;
+    readonly traceId?: string | undefined;
+    readonly status?: number | undefined;
+    readonly target?: string | undefined;
+    readonly requestId?: string | undefined;
+    readonly validation?: readonly TerraScaleValidationIssue[] | undefined;
+    readonly details?: unknown | undefined;
+};
+export type TerraScaleSuccess<TValue> = {
+    readonly ok: true;
+    readonly routeName: string;
+    readonly status: number;
+    readonly headers: Headers;
+    readonly value: TValue;
+};
+export type TerraScaleFailure = {
+    readonly ok: false;
+    readonly routeName: string;
+    readonly status?: number | undefined;
+    readonly headers?: Headers | undefined;
+    readonly error: TerraScaleError;
+    readonly body?: unknown | undefined;
+};
+export type TerraScaleResult<TValue> = TerraScaleFailure | TerraScaleSuccess<TValue>;

package/types/schema.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Field IDs must come from the application's reviewed collection binding.
+ *
+ * @param {number} id
+ * @param {string} name
+ * @param {FieldType} type
+ * @param {FieldOptions} [options]
+ * @returns {FieldDef}
+ */
+export function defineField(id: number, name: string, type: FieldType, options?: FieldOptions): FieldDef;
+/**
+ * @param {string} name
+ * @param {CollectionOptions} [options]
+ * @returns {CollectionBuilder}
+ */
+export function collection(name: string, options?: CollectionOptions): CollectionBuilder;
+/**
+ * @param {readonly (CollectionSchema | CollectionBuilder)[]} entries
+ * @returns {SchemaBuilder}
+ */
+export function defineSchema(entries: readonly (CollectionSchema | CollectionBuilder)[]): SchemaBuilder;
+/**
+ * @param {SchemaJson | SchemaBuilder} schema
+ * @returns {string}
+ */
+export function serializeSchema(schema: SchemaJson | SchemaBuilder): string;
+/**
+ * @param {SchemaJson} schema
+ * @returns {SchemaJson}
+ */
+export function normalizeSchema(schema: SchemaJson): SchemaJson;
+/**
+ * @param {SchemaJson} schema
+ * @returns {void}
+ */
+export function validateSchema(schema: SchemaJson): void;
+/**
+ * @param {CollectionSchema} schema
+ * @returns {void}
+ */
+export function validateCollection(schema: CollectionSchema): void;
+/**
+ * Validate native values using the accepted codec; never coerce integers or bytes.
+ *
+ * @param {CollectionSchema} schema
+ * @param {Readonly<Record<string, DatabaseValue>>} record
+ * @returns {readonly DatabaseField[]}
+ */
+export function encodeSchemaFields(schema: CollectionSchema, record: Readonly<Record<string, DatabaseValue>>): readonly DatabaseField[];
+/** @import { DatabaseField, DatabaseValue } from "./database-types.js" */
+/** Pure local declarations. These are not server catalog or migration requests. */
+export const FieldTypes: Readonly<{
+    readonly bool: "bool";
+    readonly i64: "i64";
+    readonly utf8: "utf8";
+    readonly bytes: "bytes";
+    readonly map: "map";
+    readonly array: "array";
+}>;
+export class SchemaValidationError extends Error {
+    /**
+     * @param {string} message
+     */
+    constructor(message: string);
+}
+/** Persistent fluent builder; each branch keeps its own declarations. */
+export class CollectionBuilder {
+    /**
+     * @param {string} name
+     * @param {CollectionOptions} [options]
+     */
+    constructor(name: string, options?: CollectionOptions);
+    /**
+     * @param {number} id
+     * @param {string} name
+     * @param {FieldType} type
+     * @param {FieldOptions} [options]
+     * @returns {CollectionBuilder}
+     */
+    field(id: number, name: string, type: FieldType, options?: FieldOptions): CollectionBuilder;
+    /**
+     * @returns {CollectionSchema}
+     */
+    build(): CollectionSchema;
+    /**
+     * @returns {string}
+     */
+    toJSON(): string;
+    #private;
+}
+export class SchemaBuilder {
+    /**
+     * @param {readonly (CollectionSchema | CollectionBuilder)[]} [entries]
+     */
+    constructor(entries?: readonly (CollectionSchema | CollectionBuilder)[]);
+    /**
+     * @param {CollectionSchema | CollectionBuilder} entry
+     * @returns {SchemaBuilder}
+     */
+    addCollection(entry: CollectionSchema | CollectionBuilder): SchemaBuilder;
+    /**
+     * @param {string} name
+     * @param {CollectionOptions} [options]
+     * @returns {SchemaBuilder}
+     */
+    collection(name: string, options?: CollectionOptions): SchemaBuilder;
+    /**
+     * @returns {SchemaJson}
+     */
+    build(): SchemaJson;
+    /**
+     * @returns {void}
+     */
+    validate(): void;
+    /**
+     * @returns {string}
+     */
+    toJSON(): string;
+    #private;
+}
+export type FieldType = (typeof FieldTypes)[keyof typeof FieldTypes];
+export type FieldOptions = {
+    readonly required?: boolean;
+};
+/**
+ * `required` refers to field presence; explicit native null remains distinct.
+ */
+export type FieldDef = {
+    readonly id: number;
+    readonly name: string;
+    readonly type: FieldType;
+    readonly required: boolean;
+};
+export type CollectionSchema = {
+    readonly name: string;
+    readonly fields: readonly FieldDef[];
+};
+export type SchemaJson = {
+    readonly collections: readonly CollectionSchema[];
+};
+export type CollectionOptions = {
+    readonly fields?: readonly FieldDef[];
+};
+import type { DatabaseValue } from "./database-types.js";
+import type { DatabaseField } from "./database-types.js";

package/types/sql.d.ts

@@ -0,0 +1,288 @@
+/**
+ * @template {SqlCollectionSchema} S
+ * @overload
+ * @param {S} schema
+ * @returns {SelectBuilder<S>}
+ */
+export function select<S extends SqlCollectionSchema>(schema: S): SelectBuilder<S>;
+/**
+ * @overload
+ * @param {readonly string[]} [columns]
+ * @returns {SelectBuilder}
+ */
+export function select(columns?: readonly string[] | undefined): SelectBuilder;
+/**
+ * @template {SqlCollectionSchema} S
+ * @param {S} schema
+ * @returns {SelectBuilder<S>}
+ */
+export function selectSchema<S extends SqlCollectionSchema>(schema: S): SelectBuilder<S>;
+/**
+ * @param {string} sql
+ * @param {readonly SqlParameter[]} [parameters]
+ * @returns {Query}
+ */
+export function raw(sql: string, parameters?: readonly SqlParameter[]): Query;
+/**
+ * Validate the client-side read-only SQL allow-list and positional bindings.
+ *
+ * @param {string} sql
+ * @param {readonly SqlParameter[]} [parameters]
+ * @returns {void}
+ */
+export function validateSql(sql: string, parameters?: readonly SqlParameter[]): void;
+export type Direction = (typeof Direction)[keyof typeof Direction];
+/** @import { CollectionSchema, FieldDef, FieldType } from "./schema.js" */
+/**
+ * @typedef {Pick<FieldDef, "name" | "type"> &
+ *   Partial<Omit<FieldDef, "name" | "type">>} SqlFieldDef
+ */
+/**
+ * @typedef {{
+ *   readonly name: string;
+ *   readonly fields: readonly SqlFieldDef[];
+ * } & Partial<Omit<CollectionSchema, "name" | "fields">>} SqlCollectionSchema
+ */
+/**
+ * @template {SqlCollectionSchema} S
+ * @typedef {S["fields"][number]} SchemaField
+ */
+/**
+ * @template {SqlCollectionSchema} S
+ * @typedef {SchemaField<S>} QueryField
+ */
+export const Direction: Readonly<{
+    readonly Asc: "ASC";
+    readonly Desc: "DESC";
+}>;
+/** @typedef {(typeof Direction)[keyof typeof Direction]} Direction */
+/** @typedef {boolean | bigint | number | string | Uint8Array | null} SqlScalar */
+/** @typedef {SqlScalar} SqlParameter */
+export class SqlValidationError extends Error {
+    /**
+     * @param {string} message
+     */
+    constructor(message: string);
+    /**
+     * @override
+     * @readonly
+     */
+    override readonly name: "SqlValidationError";
+    /** @readonly */
+    readonly code: "invalid_sql";
+}
+/** A validated, parameterized read-only SQL statement. */
+export class Query {
+    /**
+     * @param {string} sql
+     * @param {readonly SqlParameter[]} [parameters]
+     * @returns {Query}
+     */
+    static raw(sql: string, parameters?: readonly SqlParameter[]): Query;
+    /**
+     * @param {readonly string[]} [columns]
+     * @returns {SelectBuilder}
+     */
+    static select(columns?: readonly string[]): SelectBuilder;
+    /**
+     * @template {SqlCollectionSchema} S
+     * @param {S} schema
+     * @returns {SelectBuilder<S>}
+     */
+    static selectSchema<S extends SqlCollectionSchema>(schema: S): SelectBuilder<S>;
+    /**
+     * @private
+     * @param {string} sql
+     * @param {readonly SqlParameter[]} parameters
+     */
+    private constructor();
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly statement: string;
+    /**
+     * @returns {readonly SqlParameter[]}
+     */
+    get parameters(): readonly SqlParameter[];
+    /**
+     * @returns {QueryDescriptor}
+     */
+    toDescriptor(): QueryDescriptor;
+    #private;
+}
+/**
+ * Schema-bound SELECT builder.
+ *
+ * @template {SqlCollectionSchema} [S=SqlCollectionSchema]
+ */
+export class SelectBuilder<S extends SqlCollectionSchema = SqlCollectionSchema> {
+    /**
+     * @param {readonly string[]} columns
+     * @returns {SelectBuilder}
+     */
+    static fromColumns(columns: readonly string[]): SelectBuilder;
+    /**
+     * @template {SqlCollectionSchema} T
+     * @param {T} schema
+     * @returns {SelectBuilder<T>}
+     */
+    static fromSchema<T extends SqlCollectionSchema>(schema: T): SelectBuilder<T>;
+    /**
+     * @private
+     * @param {{
+     *   columns: readonly string[];
+     *   from?: string | undefined;
+     *   schema?: S | undefined;
+     *   predicates?: readonly string[];
+     *   order?: readonly (readonly [string, Direction])[];
+     *   limit?: number | undefined;
+     *   offset?: number | undefined;
+     *   parameters?: readonly SqlParameter[];
+     *   schemaBound?: boolean;
+     * }} input
+     */
+    private constructor();
+    /**
+     * @param {QueryField<S>} field
+     * @returns {SelectBuilder<S>}
+     */
+    column(field: QueryField<S>): SelectBuilder<S>;
+    /**
+     * @param {readonly QueryField<S>[]} fields
+     * @returns {SelectBuilder<S>}
+     */
+    columns(fields: readonly QueryField<S>[]): SelectBuilder<S>;
+    /**
+     * @param {string} collection
+     * @returns {SelectBuilder<S>}
+     */
+    from(collection: string): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereEq<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereNe<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereGt<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereGte<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereLt<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereLte<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {T} value
+     * @returns {SelectBuilder<S>}
+     */
+    whereLike<T extends SqlParameter>(field: QueryField<S>, value: T): SelectBuilder<S>;
+    /**
+     * @template {SqlParameter} T
+     * @param {QueryField<S>} field
+     * @param {readonly T[]} values
+     * @returns {SelectBuilder<S>}
+     */
+    whereIn<T extends SqlParameter>(field: QueryField<S>, values: readonly T[]): SelectBuilder<S>;
+    /**
+     * @param {SchemaField<S>} field
+     * @param {Direction} [direction]
+     * @returns {SelectBuilder<S>}
+     */
+    orderByField(field: SchemaField<S>, direction?: Direction): SelectBuilder<S>;
+    /**
+     * @param {string} column
+     * @param {Direction} [direction]
+     * @returns {SelectBuilder<S>}
+     */
+    orderBy(column: string, direction?: Direction): SelectBuilder<S>;
+    /**
+     * @param {number} value
+     * @returns {SelectBuilder<S>}
+     */
+    limit(value: number): SelectBuilder<S>;
+    /**
+     * @param {number} value
+     * @returns {SelectBuilder<S>}
+     */
+    offset(value: number): SelectBuilder<S>;
+    /**
+     * @param {{
+     *   readonly limit: number;
+     *   readonly offset?: number | undefined;
+     * }} options
+     * @returns {SelectBuilder<S>}
+     */
+    paginate(options: {
+        readonly limit: number;
+        readonly offset?: number | undefined;
+    }): SelectBuilder<S>;
+    /**
+     * @param {number} page
+     * @param {number} pageSize
+     * @returns {SelectBuilder<S>}
+     */
+    page(page: number, pageSize: number): SelectBuilder<S>;
+    /**
+     * @returns {Query}
+     */
+    build(): Query;
+    /**
+     * @returns {QueryDescriptor}
+     */
+    toDescriptor(): QueryDescriptor;
+    #private;
+}
+/**
+ * Validate the client-side read-only SQL allow-list and positional bindings.
+ *
+ * @param {string} sql
+ * @param {readonly SqlParameter[]} [parameters]
+ * @returns {void}
+ */
+export function validate_sql(sql: string, parameters?: readonly SqlParameter[]): void;
+export type QueryDescriptor = {
+    readonly statement: string;
+    readonly parameters: readonly SqlParameter[];
+};
+export type SqlFieldDef = Pick<FieldDef, "name" | "type"> & Partial<Omit<FieldDef, "name" | "type">>;
+export type SqlCollectionSchema = {
+    readonly name: string;
+    readonly fields: readonly SqlFieldDef[];
+} & Partial<Omit<CollectionSchema, "name" | "fields">>;
+export type SchemaField<S extends SqlCollectionSchema> = S["fields"][number];
+export type QueryField<S extends SqlCollectionSchema> = SchemaField<S>;
+export type SqlScalar = boolean | bigint | number | string | Uint8Array | null;
+export type SqlParameter = SqlScalar;
+import type { FieldDef } from "./schema.js";
+import type { CollectionSchema } from "./schema.js";

package/types/svelte/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The Svelte store contract; `$store` auto-subscription binds to it directly.
+ *
+ * @typedef {() => void} SvelteUnsubscriber
+ */
+/**
+ * @template TValue
+ * @typedef {(value: TValue) => void} SvelteSubscriber
+ */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly subscribe: (run: SvelteSubscriber<TValue>) => SvelteUnsubscriber;
+ * }} SvelteReadable
+ */
+/**
+ * A query store; `refetch` restarts delivery from a fresh generation, like
+ * the React `refetch`.
+ *
+ * @template TValue
+ * @typedef {SvelteReadable<ReactiveQueryState<TValue>> & {
+ *   readonly refetch: () => void;
+ * }} SvelteQuery
+ */
+/**
+ * One reactive query as a Svelte store. The observer lifecycle follows the
+ * store subscription count, so `$query` in a component starts delivery on
+ * mount and disposes the transport on unmount. Keep the source object stable
+ * between renders.
+ *
+ * @template TValue
+ * @param {ReactiveQuerySource<TValue>} source
+ * @param {ReactiveQueryOptions<TValue>} [options]
+ * @returns {SvelteQuery<TValue>}
+ */
+export function createQuery<TValue>(source: ReactiveQuerySource<TValue>, options?: ReactiveQueryOptions<TValue>): SvelteQuery<TValue>;
+/**
+ * @template TValue, TVariables
+ * @typedef {SvelteReadable<ReactiveMutationState<TValue>> & {
+ *   readonly mutate: (variables: TVariables) => void;
+ *   readonly mutateAsync: (variables: TVariables) => Promise<TValue>;
+ *   readonly cancel: () => void;
+ *   readonly reset: () => void;
+ * }} SvelteMutation
+ */
+/**
+ * A durable mutation as a Svelte store; `$mutation.isPending` drives the UI.
+ *
+ * @template TValue
+ * @template [TVariables=void]
+ * @param {ReactiveMutationOptions<TValue, TVariables>} options
+ * @returns {SvelteMutation<TValue, TVariables>}
+ */
+export function createMutation<TValue, TVariables = void>(options: ReactiveMutationOptions<TValue, TVariables>): SvelteMutation<TValue, TVariables>;
+export * from "../react/core.js";
+/**
+ * The Svelte store contract; `$store` auto-subscription binds to it directly.
+ */
+export type SvelteUnsubscriber = () => void;
+export type SvelteSubscriber<TValue> = (value: TValue) => void;
+export type SvelteReadable<TValue> = {
+    readonly subscribe: (run: SvelteSubscriber<TValue>) => SvelteUnsubscriber;
+};
+/**
+ * A query store; `refetch` restarts delivery from a fresh generation, like
+ * the React `refetch`.
+ */
+export type SvelteQuery<TValue> = SvelteReadable<ReactiveQueryState<TValue>> & {
+    readonly refetch: () => void;
+};
+export type SvelteMutation<TValue, TVariables> = SvelteReadable<ReactiveMutationState<TValue>> & {
+    readonly mutate: (variables: TVariables) => void;
+    readonly mutateAsync: (variables: TVariables) => Promise<TValue>;
+    readonly cancel: () => void;
+    readonly reset: () => void;
+};
+import type { ReactiveQuerySource } from "../react/core.js";
+import type { ReactiveQueryOptions } from "../react/core.js";
+import type { ReactiveMutationOptions } from "../react/core.js";
+import type { ReactiveQueryState } from "../react/core.js";
+import type { ReactiveMutationState } from "../react/core.js";