@loams/client 0.1.0 → 0.1.1

package/dist/loams.d.ts

@@ -1,5 +1,7 @@
 import type { Transport } from '@connectrpc/connect';
-import { type AdminAgentsModule, type AdminAuditModule, type AdminKeysModule, type AdminOrgModule, type AdminProjectsModule, type AuthModule, type CallBinding, type InstanceModule, type LiveAdminModule, type LiveModule, type ModuleBinding, type TablesModule } from './gen/facade.js';
+import { type AdminAgentsModule, type AdminAuditModule, type AdminKeysModule, type AdminOrgModule, type AdminProjectsModule, type AuthModule, type CallBinding, type CollectionsModule, type DocumentsModule, type GraphModule, type SqlModule, type StreamsModule, type NamespacesModule, type SearchModule, type VectorModule, type InstanceModule, type LiveAdminModule, type LiveModule, type ModuleBinding, type TablesModule } from './gen/facade.js';
+import { type documentCalls, type searchCalls, type sqlCalls, type streamCalls } from './app.js';
+import { CollectionHandle } from './handle.js';
 import { type CallOptions, type ConsistencyTokenStore } from './runtime/call.js';
 import { type PageRequestOptions } from './runtime/pagination.js';
 import { SystemApi } from './system.js';
@@ -38,8 +40,29 @@ export interface LoamsOptions {
      * read-your-writes across processes.
      */
     sessionConsistency?: boolean;
-    /** The client's deadline, when the transport does not set one. */
+    /**
+     * The deadline of every unary call that does not set its own `timeoutMs`
+     * (runtime contract R12). Default 30 000 ms; `0` disables it. Streams have
+     * no default deadline. The budget covers a call's retries, and a call that
+     * runs out raises `DeadlineExceededError` with reason
+     * `client_deadline_exceeded`, which is never retried.
+     */
     timeoutMs?: number;
+    /**
+     * The namespace of every request that has a `namespace` field and leaves it
+     * empty (runtime contract R11). An explicit `namespace` always wins; with
+     * neither, such a call fails with `InvalidArgumentError` before any network
+     * call.
+     */
+    namespace?: string;
+}
+/** The environment `Loams.fromEnv` reads (R1). */
+export interface LoamsEnvironment {
+    readonly LOAMS_ENDPOINT?: string;
+    readonly LOAMS_API_KEY?: string;
+    readonly LOAMS_TOKEN?: string;
+    readonly LOAMS_NAMESPACE?: string;
+    readonly [name: string]: string | undefined;
 }
 export type { Catalogue, VersionReport } from './system.js';
 /** The generated modules, keyed by name. A module the generator has not seen
@@ -56,6 +79,27 @@ export type LiveNamespace = LiveModule & {
     /** `loams.live.admin` — apps, deploy, roll back, index status and logs. */
     readonly admin: LiveAdminModule;
 };
+/** A paged call's `<call>All` iterator, which `attachAppCalls` adds. */
+type AllOf<Item> = (request?: object, options?: CallOptions) => AsyncGenerator<Item, void, undefined>;
+/** `loams.namespaces`, with `listAll`. */
+export type NamespacesNamespace = NamespacesModule & {
+    readonly listAll: AllOf<unknown>;
+};
+/** `loams.collections`, with `listAll` and `listVersionsAll`. */
+export type CollectionsNamespace = CollectionsModule & {
+    readonly listAll: AllOf<unknown>;
+    readonly listVersionsAll: AllOf<unknown>;
+};
+/** `loams.documents`, with the hand-written conveniences (SDKP §2.3). */
+export type DocumentsNamespace = DocumentsModule & ReturnType<typeof documentCalls>;
+/** `loams.search`, with `text`, `hybrid` and `queryAll` (SDKP §2.4). */
+export type SearchNamespace = SearchModule & ReturnType<typeof searchCalls>;
+/** `loams.sql`, with `records` (SDKP §2.5). */
+export type SqlNamespace = SqlModule & ReturnType<typeof sqlCalls>;
+/** `loams.streams`, with `subscribe` and `<call>All` (SDKP §2.5, R14). */
+export type StreamsNamespace = StreamsModule & ReturnType<typeof streamCalls> & {
+    readonly listAll: AllOf<unknown>;
+};
 /** `loams.admin`: the console's administration modules (design §44 §7.2). */
 export interface AdminNamespace {
     readonly agents: AdminAgentsModule;
@@ -78,13 +122,44 @@ export declare class Loams {
     readonly admin: AdminNamespace;
     /** `loams.auth` — sessions and sign-in. */
     readonly auth: AuthModule;
+    /** `loams.namespaces` — the containers every collection and stream live in. */
+    readonly namespaces: NamespacesNamespace;
+    /** `loams.collections` — collections, their schemas, aliases and versions. */
+    readonly collections: CollectionsNamespace;
+    /** `loams.documents` — write, read, scroll and count documents. */
+    readonly documents: DocumentsNamespace;
+    /** `loams.search` — text, vector and hybrid search (`Search` builds one). */
+    readonly search: SearchNamespace;
+    /** `loams.vector` — the kNN half of `search`, by its own name (Q613). */
+    readonly vector: VectorModule;
+    /** `loams.graph` — Loams Graph, queried with GQL. Its package is `unstable`. */
+    readonly graph: GraphModule;
+    /** `loams.sql` — one read-only SQL statement over a namespace's collections. */
+    readonly sql: SqlNamespace;
+    /** `loams.streams` — a namespace's logs: produce, fetch, CloudEvents and `subscribe`. */
+    readonly streams: StreamsNamespace;
     /** The module catalogue, feature detection and the version check. */
     readonly system: SystemApi;
     /** Every generated module, by its dotted name (`'live.admin'`): the
      * catalogue a caller iterates. The same objects are reachable as
      * properties, `loams.live.admin` for `'live.admin'`. */
     readonly modules: Readonly<Record<string, unknown>>;
+    /** The default namespace (R11), if the client has one. */
+    readonly namespace: string | undefined;
     constructor(options: LoamsOptions);
+    /**
+     * A client from the environment: `LOAMS_ENDPOINT`, then `LOAMS_API_KEY` or
+     * `LOAMS_TOKEN`, then `LOAMS_NAMESPACE` (R1). `options` wins over the
+     * environment where both say something.
+     */
+    static fromEnv(options?: Partial<LoamsOptions>, environment?: LoamsEnvironment): Loams;
+    /**
+     * A handle on one collection: its document and search calls with
+     * `collection` (and `namespace`) filled in (SDKP §2.8). Holds no state.
+     */
+    collection(name: string, options?: {
+        namespace?: string;
+    }): CollectionHandle;
     /** The session consistency token store, when `sessionConsistency` is on. */
     get consistency(): ConsistencyTokenStore | undefined;
     /** The generated module bindings, as the SDK sees them. */

package/dist/loams.js

@@ -16,13 +16,15 @@
 // why annotating a proto is enough to add an SDK method.
 import { Code } from '@connectrpc/connect';
 import { MODULES, PROTO_PACKAGES, PROTO_REV, SERVICE_DESCRIPTORS, } from './gen/facade.js';
-import { CallInvoker } from './runtime/call.js';
+import { attachAppCalls } from './app.js';
+import { CollectionHandle } from './handle.js';
+import { CallInvoker, DEFAULT_TIMEOUT_MS, } from './runtime/call.js';
 import { ConsistencySession } from './runtime/consistency.js';
 import { LoamsError } from './runtime/errors.js';
 import { paginate } from './runtime/pagination.js';
 import { SystemApi } from './system.js';
 import { DEFAULT_MAX_RETRIES } from './runtime/retry.js';
-import { apiKey } from './runtime/token-source.js';
+import { apiKey, envToken } from './runtime/token-source.js';
 import { createLoamsTransport } from './runtime/transports.js';
 import { watch } from './runtime/streams.js';
 /** One SDK, over one instance. */
@@ -38,12 +40,30 @@ export class Loams {
     admin;
     /** `loams.auth` — sessions and sign-in. */
     auth;
+    /** `loams.namespaces` — the containers every collection and stream live in. */
+    namespaces;
+    /** `loams.collections` — collections, their schemas, aliases and versions. */
+    collections;
+    /** `loams.documents` — write, read, scroll and count documents. */
+    documents;
+    /** `loams.search` — text, vector and hybrid search (`Search` builds one). */
+    search;
+    /** `loams.vector` — the kNN half of `search`, by its own name (Q613). */
+    vector;
+    /** `loams.graph` — Loams Graph, queried with GQL. Its package is `unstable`. */
+    graph;
+    /** `loams.sql` — one read-only SQL statement over a namespace's collections. */
+    sql;
+    /** `loams.streams` — a namespace's logs: produce, fetch, CloudEvents and `subscribe`. */
+    streams;
     /** The module catalogue, feature detection and the version check. */
     system;
     /** Every generated module, by its dotted name (`'live.admin'`): the
      * catalogue a caller iterates. The same objects are reachable as
      * properties, `loams.live.admin` for `'live.admin'`. */
     modules;
+    /** The default namespace (R11), if the client has one. */
+    namespace;
     #invoker;
     #consistency;
     constructor(options) {
@@ -59,20 +79,62 @@ export class Loams {
         // that asks for the session's consistency token reads and records through
         // the same store the client exposes.
         this.#consistency = options.sessionConsistency === true ? new ConsistencySession() : undefined;
-        this.#invoker = new CallInvoker(transport, tokenSource, options.maxRetries ?? DEFAULT_MAX_RETRIES, this.#consistency);
+        this.#invoker = new CallInvoker(transport, tokenSource, options.maxRetries ?? DEFAULT_MAX_RETRIES, this.#consistency, {
+            namespace: options.namespace,
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        });
+        this.namespace = options.namespace;
         this.modules = buildModules(this.#invoker);
+        attachAppCalls(this.modules, MODULES);
         const tree = nestModules(this.modules);
         this.instance = tree.instance;
         this.live = tree.live;
         this.tables = tree.tables;
         this.admin = tree.admin;
         this.auth = tree.auth;
+        this.namespaces = tree.namespaces;
+        this.collections = tree.collections;
+        this.documents = tree.documents;
+        this.search = tree.search;
+        this.vector = tree.vector;
+        this.graph = tree.graph;
+        this.sql = tree.sql;
+        this.streams = tree.streams;
         this.system = new SystemApi((request, callOptions) => this.instance.getInstance(request, callOptions), {
             endpoint: options.endpoint,
             maxRetries: options.maxRetries,
             timeoutMs: options.timeoutMs,
         });
     }
+    /**
+     * A client from the environment: `LOAMS_ENDPOINT`, then `LOAMS_API_KEY` or
+     * `LOAMS_TOKEN`, then `LOAMS_NAMESPACE` (R1). `options` wins over the
+     * environment where both say something.
+     */
+    static fromEnv(options = {}, environment = readEnvironment()) {
+        const endpoint = options.endpoint ?? environment.LOAMS_ENDPOINT;
+        if (endpoint === undefined || endpoint === '') {
+            throw new LoamsError('Loams.fromEnv: LOAMS_ENDPOINT is not set', {
+                code: Code.InvalidArgument,
+                metadata: { field: 'LOAMS_ENDPOINT' },
+            });
+        }
+        const hasKey = (environment.LOAMS_API_KEY ?? '') !== '' || (environment.LOAMS_TOKEN ?? '') !== '';
+        const namespace = options.namespace ?? environment.LOAMS_NAMESPACE;
+        return new Loams({
+            ...options,
+            endpoint,
+            ...(options.auth === undefined && hasKey ? { auth: envToken(environment) } : {}),
+            ...(namespace === undefined || namespace === '' ? {} : { namespace }),
+        });
+    }
+    /**
+     * A handle on one collection: its document and search calls with
+     * `collection` (and `namespace`) filled in (SDKP §2.8). Holds no state.
+     */
+    collection(name, options = {}) {
+        return new CollectionHandle(this.modules, name, options);
+    }
     /** The session consistency token store, when `sessionConsistency` is on. */
     get consistency() {
         return this.#consistency;
@@ -130,6 +192,12 @@ export class Loams {
         this.system.invalidate();
     }
 }
+/** The process environment, where there is one (Node, Deno, Bun); empty in a
+ * browser. */
+function readEnvironment() {
+    const scope = globalThis;
+    return scope.process?.env ?? {};
+}
 /**
  * Builds one object per generated module: one function per generated call,
  * each delegating to the same invoker.
@@ -141,11 +209,21 @@ export class Loams {
 function buildModules(invoker) {
     const modules = {};
     for (const module of MODULES) {
-        const descriptor = SERVICE_DESCRIPTORS[module.service];
-        if (descriptor === undefined) {
+        // A module may span two services (`loams.graph` is `GraphAdminService`
+        // and `GraphService`), so every call's own service is registered.
+        const services = new Set([module.service, ...module.calls.map((call) => call.service)]);
+        let missing = false;
+        for (const service of services) {
+            const descriptor = SERVICE_DESCRIPTORS[service];
+            if (descriptor === undefined) {
+                missing = true;
+                continue;
+            }
+            invoker.register(service, descriptor);
+        }
+        if (missing) {
             continue;
         }
-        invoker.register(module.service, descriptor);
         const calls = {
             module: module.name,
             service: module.service,

package/dist/runtime/batch.d.ts

@@ -0,0 +1,29 @@
+import type { CallOptions } from './call.js';
+/** The default chunk bounds (§44 §7.5). */
+export declare const DEFAULT_CHUNK_ROWS = 10000;
+export declare const DEFAULT_CHUNK_BYTES: number;
+/** How `writeBatch` chunks. */
+export interface BatchOptions {
+    /** The most operations in one chunk. Default 10 000. */
+    chunkRows?: number;
+    /** The most bytes of operation JSON in one chunk. Default 4 MiB. A single
+     * operation larger than this goes in a chunk of its own. */
+    chunkBytes?: number;
+}
+/** What a finished batch reports. */
+export interface BatchResult {
+    /** The merge of every chunk's consistency token. */
+    readonly token: string | undefined;
+    /** How many chunks were written. */
+    readonly chunks: number;
+    /** How many operations those chunks carried. */
+    readonly rows: number;
+}
+/** Sends one chunk; `idempotencyKey` is that chunk's own key. */
+export type ChunkWriter<Op> = (ops: Op[], options: CallOptions & {
+    idempotencyKey: string;
+}) => Promise<{
+    token?: string;
+} | undefined>;
+/** Splits `ops` into chunks and writes them one after another. */
+export declare function writeBatch<Op>(write: ChunkWriter<Op>, ops: Iterable<Op> | AsyncIterable<Op>, options?: BatchOptions & CallOptions): Promise<BatchResult>;

package/dist/runtime/batch.js

@@ -0,0 +1,95 @@
+// `documents.writeBatch` (runtime contract R13, SDKP §2.3; design §44 §7.5).
+//
+// A bulk load as a loop of ordinary `WriteDocuments` calls, chunked by rows
+// and by bytes:
+//
+// - **One chunk in flight at a time.** Order is preserved and a failure stops
+//   the load at a known point, which concurrency would blur.
+// - **One idempotency key per chunk**, minted before the chunk's first attempt
+//   and reused on every retry of that chunk, so a retried chunk is the same
+//   write (D610) and two chunks are never mistaken for one.
+// - **The tokens merge.** The result is the merge of every chunk's
+//   consistency token, so a read held to it sees the whole load.
+// - **The first failed chunk stops the load** with a `BatchError` that says
+//   how many chunks (and documents) were applied before it, and carries their
+//   merged token. Those chunks stay applied; nothing is rolled back.
+//
+// Browser-safe: sizes are measured with `TextEncoder`, not `Buffer`.
+import { Code } from '@connectrpc/connect';
+import { ConsistencyToken } from './consistency.js';
+import { BatchError, toLoamsError } from './errors.js';
+import { uuidv7 } from './uuidv7.js';
+/** The default chunk bounds (§44 §7.5). */
+export const DEFAULT_CHUNK_ROWS = 10_000;
+export const DEFAULT_CHUNK_BYTES = 4 * 1024 * 1024;
+const encoder = new TextEncoder();
+function sizeOf(op) {
+    return encoder.encode(JSON.stringify(op, (_key, value) => typeof value === 'bigint' ? value.toString() : value)).length;
+}
+function mergeToken(current, next) {
+    if (next === undefined || next === '') {
+        return current;
+    }
+    try {
+        const parsed = ConsistencyToken.parse(next);
+        return current === undefined ? parsed.normalized() : current.merge(parsed);
+    }
+    catch {
+        return current;
+    }
+}
+/** Splits `ops` into chunks and writes them one after another. */
+export async function writeBatch(write, ops, options = {}) {
+    const { chunkRows = DEFAULT_CHUNK_ROWS, chunkBytes = DEFAULT_CHUNK_BYTES, ...call } = options;
+    if (!(chunkRows > 0) || !(chunkBytes > 0)) {
+        throw new RangeError('writeBatch: chunkRows and chunkBytes must be positive');
+    }
+    let token;
+    let chunks = 0;
+    let rows = 0;
+    let pending = [];
+    let pendingBytes = 0;
+    const flush = async () => {
+        if (pending.length === 0) {
+            return;
+        }
+        const chunk = pending;
+        pending = [];
+        pendingBytes = 0;
+        try {
+            // The key is minted here, once per chunk, and the invoker reuses it on
+            // every retry of this chunk.
+            const answer = await write(chunk, { ...call, idempotencyKey: uuidv7() });
+            token = mergeToken(token, answer?.token);
+        }
+        catch (thrown) {
+            const cause = toLoamsError(thrown);
+            throw new BatchError(`writeBatch stopped at chunk ${chunks + 1}: ${chunks} chunks (${rows} operations) were applied before it; ${cause.message}`, {
+                code: cause.code === Code.Unknown ? Code.Aborted : cause.code,
+                reason: 'batch_partially_applied',
+                metadata: {
+                    chunks_applied: String(chunks),
+                    rows_applied: String(rows),
+                    ...(cause.reason === undefined ? {} : { cause_reason: cause.reason }),
+                },
+                rpc: cause.rpc,
+                cause,
+                chunksApplied: chunks,
+                rowsApplied: rows,
+                token: token?.toString(),
+            });
+        }
+        chunks += 1;
+        rows += chunk.length;
+    };
+    for await (const op of ops) {
+        const size = sizeOf(op);
+        if (pending.length > 0 && (pending.length >= chunkRows || pendingBytes + size > chunkBytes)) {
+            await flush();
+        }
+        pending.push(op);
+        pendingBytes += size;
+    }
+    await flush();
+    return { token: token?.toString(), chunks, rows };
+}

package/dist/runtime/call.d.ts

@@ -26,6 +26,14 @@ export interface CallOptions extends ConnectCallOptions {
     /** The consistency token to read at, and the store to record writes in
      * (§44 §7.4, D609). */
     consistency?: ConsistencyOptions;
+    /**
+     * This call's deadline in milliseconds (runtime contract R12). Unary calls
+     * default to the client's `timeoutMs` (30 s); streams have none unless one is
+     * given here. `0` means no deadline. The whole call, retries included, has to
+     * fit: a call that runs out raises `DeadlineExceededError` with reason
+     * `client_deadline_exceeded` and is never retried.
+     */
+    timeoutMs?: number;
 }
 /** How consistency tokens are carried (D609). */
 export interface ConsistencyOptions {
@@ -33,15 +41,18 @@ export interface ConsistencyOptions {
      * / `'eventual'` to read without waiting. */
     token?: string;
     /** Record the consistency token every response carries, so later reads are
-     * read-your-writes without the caller threading tokens by hand. */
+     * read-your-writes without the caller threading tokens by hand. Unset means
+     * the client's session, when `sessionConsistency` is on; `false` opts this
+     * call out. */
     session?: ConsistencyTokenStore | true | false;
 }
 /** A session's merged consistency token (D609). Off unless a call opts in. */
 export interface ConsistencyTokenStore {
-    /** The token to attach to the next read, or undefined for none. */
-    current(): string | undefined;
-    /** Folds a token the server returned into the session's. */
-    record(token: string | undefined): void;
+    /** The token to attach to the next read in `scope` (a proto package), or
+     * undefined for none. */
+    current(scope?: string): string | undefined;
+    /** Folds a token the server returned, in `scope`, into the session's. */
+    record(token: string | undefined, scope?: string): void;
 }
 /** One attempt of a call, as the transport sees it. */
 export type Send = (attempt: Attempt) => Promise<unknown>;
@@ -60,6 +71,8 @@ export interface RetryPlan {
     readonly maxRetries: number;
     readonly signal?: AbortSignal;
     readonly onRefresh?: () => Promise<void>;
+    /** True once the call's own deadline has passed: no further attempt. */
+    readonly expired?: () => boolean;
 }
 /**
  * Runs `send` until it answers or the plan says stop, and returns whatever it
@@ -87,6 +100,31 @@ declared?: boolean): {
     request: unknown;
     keyed: boolean;
 };
+/** The unary deadline when neither the client nor the call sets one (R12). */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** The response header a consistency token is read from (R4). */
+export declare const CONSISTENCY_TOKEN_HEADER = "loams-consistency-token";
+/**
+ * The packages whose `namespace` field is a Loams namespace (R11) and whose
+ * `consistency` field reads at a consistency token (R4). Other packages have
+ * fields of the same name that mean something else: `loams.live.v1`'s
+ * `CreateAppRequest.namespace` is free text naming an app's environment, and
+ * must never be filled from, or refused for lack of, the client's default.
+ */
+export declare const APP_PACKAGES: ReadonlySet<string>;
+/**
+ * The packages whose reads take the session's token as `at_least` (R4,
+ * SDKP-17): collections and SQL. A graph's token names one graph's stream and
+ * a Graph read refuses any other, so graph reads never take the session's.
+ */
+export declare const SESSION_PACKAGES: ReadonlySet<string>;
+/** Options the invoker applies to every call (R11, R12). */
+export interface InvokerDefaults {
+    /** The namespace a request with an empty `namespace` field is sent with. */
+    namespace?: string;
+    /** The unary deadline; `0` disables it. */
+    timeoutMs?: number;
+}
 /**
  * The client's call path: a generated `CallBinding` plus a request becomes a
  * response message, with everything the SDK owns applied on the way.
@@ -98,17 +136,31 @@ export declare class CallInvoker {
     private readonly consistency;
     private readonly clients;
     private readonly descriptors;
-    /** Whether a call's request schema declares `idempotency_key`, per RPC. */
-    private readonly keyed;
-    constructor(transport: Transport, tokenSource: TokenSource | undefined, maxRetries: number, consistency: ConsistencyTokenStore | undefined);
+    /** What each RPC's request schema declares, per RPC. */
+    private readonly shapes;
+    private readonly defaults;
+    constructor(transport: Transport, tokenSource: TokenSource | undefined, maxRetries: number, consistency: ConsistencyTokenStore | undefined, defaults?: InvokerDefaults);
+    /** The client's default namespace, if it has one (R11). */
+    get namespace(): string | undefined;
     /**
      * A module's Connect client, built once from the service descriptor
      * `protoc-gen-es` generated. This is what makes the facade generated rather
      * than hand-written: the SDK never writes a client, it wraps the stubs.
      */
     register(service: string, descriptor: DescService): void;
+    /** What this call's request message declares. */
+    private shape;
     /** Whether this call's request message declares an `idempotency_key`. */
     private takesIdempotencyKey;
+    /**
+     * The request as it goes out: the default namespace filled in (R11) and the
+     * session's token set as `consistency.at_least` when the caller left
+     * `consistency` unset (R4). A request the caller set either on is left as
+     * written: an explicit argument always wins.
+     */
+    private prepare;
+    /** The deadline a unary call runs under, in milliseconds, or undefined. */
+    private unaryTimeout;
     /** The connect-es method a binding names, or a clear internal error. */
     private method;
     /** One unary call: the whole runtime contract, applied to one binding. */
@@ -127,6 +179,8 @@ export declare class CallInvoker {
     stream(binding: CallBinding, request: unknown, options?: CallOptions): AsyncIterable<unknown>;
     /** Wraps an iterable so every throw becomes a `LoamsError`. */
     private mapped;
-    /** Merges the consistency token a write answered with into the session. */
+    /** Merges every consistency token a response carried into the session:
+     * `consistency_token`, `token` and `read_token`, and the
+     * `loams-consistency-token` header (R4, SDKP §2.1). */
     private recordConsistency;
 }