@k2b/rsql 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentin Kolb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @k2b/rsql
+
+Type-safe, fetch-based client for the
+[rsql](https://github.com/k2b-dev/rsql) HTTP API. It runs in Bun, Node, and
+modern browsers without runtime dependencies.
+
+## Install
+
+```bash
+bun add @k2b/rsql
+```
+
+## Usage
+
+```ts
+import { createRsqlClient } from "@k2b/rsql";
+
+const client = createRsqlClient({
+  url: "http://127.0.0.1:8080",
+  token: "secret",
+});
+
+const contacts = client.ns("crm").table<{
+  id: number;
+  name: string;
+  status: "active" | "inactive";
+}>("contacts");
+
+const result = await contacts.rows.list({
+  status: "eq.active",
+  order: "name.asc",
+});
+
+if (result.ok) {
+  console.log(result.data);
+}
+```
+
+Modules are hierarchical and stateless:
+
+```text
+client.namespaces
+client.ns(name).tables
+client.ns(name).table(name).schema
+client.ns(name).table(name).indexes
+client.ns(name).table(name).rows
+client.ns(name).query
+client.ns(name).changelog
+client.ns(name).overview
+client.ns(name).events
+```
+
+HTTP errors resolve to `RsqlResult<T>`. Network and runtime failures may reject
+the promise. Export methods return the native streaming `Response`; SSE
+subscriptions expose an async iterable and explicit `close` function.
+
+## Default Client
+
+The `rsql` export reads `RSQL_URL` and `RSQL_API_TOKEN` lazily on first access:
+
+```ts
+import { rsql } from "@k2b/rsql";
+
+await rsql.namespaces.list();
+```
+
+Imports remain browser-safe because environment variables are not read during
+module evaluation. Browser applications should use an explicit client and must
+not expose a server-wide administrative token.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun test
+bun run test:package
+```
+
+Performance profiles are available through `bun run perf:fast` and
+`bun run perf:deep`.

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import type { CreateRsqlClientOptions, RsqlClient } from "./types.js";
+export declare const createRsqlClient: (options: CreateRsqlClientOptions) => RsqlClient;

package/dist/client.js

@@ -0,0 +1,12 @@
+import { createHttpClient } from "./http.js";
+import { createNamespaceModule } from "./modules/namespace.js";
+import { createNamespacesModule } from "./modules/namespaces.js";
+export const createRsqlClient = (options) => {
+    const http = createHttpClient(options);
+    return {
+        namespaces: createNamespacesModule(http),
+        ns(name) {
+            return createNamespaceModule(http, name);
+        },
+    };
+};

package/dist/default.d.ts

@@ -0,0 +1,2 @@
+import type { RsqlClient } from "./types.js";
+export declare const rsql: RsqlClient;

package/dist/default.js

@@ -0,0 +1,28 @@
+import { createRsqlClient } from "./client.js";
+let defaultClient = null;
+const readEnv = (key) => {
+    const maybeProcess = globalThis.process;
+    return maybeProcess?.env?.[key];
+};
+const createDefaultClient = () => {
+    const url = readEnv("RSQL_URL");
+    const token = readEnv("RSQL_API_TOKEN");
+    if (!url || !token) {
+        throw new Error("RSQL_URL and RSQL_API_TOKEN environment variables are required.\n" +
+            "You can also create an explicit client:\n" +
+            "  createRsqlClient({ url: \"http://127.0.0.1:8080\", token: \"secret\" })");
+    }
+    return createRsqlClient({ url, token });
+};
+export const rsql = new Proxy({}, {
+    get(_target, prop, receiver) {
+        if (defaultClient === null) {
+            defaultClient = createDefaultClient();
+        }
+        const value = Reflect.get(defaultClient, prop, receiver);
+        if (typeof value === "function") {
+            return value.bind(defaultClient);
+        }
+        return value;
+    },
+});

package/dist/http.d.ts

@@ -0,0 +1,8 @@
+import type { CreateRsqlClientOptions, QueryInput, RsqlResult } from "./types.js";
+export interface HttpClient {
+    json<T>(path: string, init?: RequestInit): Promise<RsqlResult<T>>;
+    empty(path: string, init?: RequestInit): Promise<RsqlResult<void>>;
+    raw(path: string, init?: RequestInit): Promise<RsqlResult<Response>>;
+    withQuery(path: string, query?: QueryInput): string;
+}
+export declare const createHttpClient: (options: CreateRsqlClientOptions) => HttpClient;

package/dist/http.js

@@ -0,0 +1,134 @@
+const defaultHeaders = (token) => ({
+    Authorization: `Bearer ${token}`,
+});
+export const createHttpClient = (options) => {
+    const baseUrl = options.url.replace(/\/$/, "");
+    const doFetch = options.fetch ?? fetch;
+    const execute = async (path, init) => {
+        const headers = new Headers(defaultHeaders(options.token));
+        if (init?.headers) {
+            const incoming = new Headers(init.headers);
+            for (const [k, v] of incoming.entries()) {
+                headers.set(k, v);
+            }
+        }
+        return doFetch(`${baseUrl}${path}`, {
+            ...init,
+            headers,
+        });
+    };
+    return {
+        async json(path, init) {
+            const res = await execute(path, init);
+            if (!res.ok) {
+                return errorResult(res);
+            }
+            if (res.status === 204) {
+                return {
+                    ok: true,
+                    data: undefined,
+                    status: res.status,
+                    headers: res.headers,
+                };
+            }
+            const data = (await res.json());
+            return {
+                ok: true,
+                data,
+                status: res.status,
+                headers: res.headers,
+            };
+        },
+        async empty(path, init) {
+            const res = await execute(path, init);
+            if (!res.ok) {
+                return errorResult(res);
+            }
+            return {
+                ok: true,
+                data: undefined,
+                status: res.status,
+                headers: res.headers,
+            };
+        },
+        async raw(path, init) {
+            const res = await execute(path, init);
+            if (!res.ok) {
+                return errorResult(res);
+            }
+            return {
+                ok: true,
+                data: res,
+                status: res.status,
+                headers: res.headers,
+            };
+        },
+        withQuery(path, query) {
+            if (!query) {
+                return path;
+            }
+            const search = toSearchParams(query);
+            const qs = search.toString();
+            if (!qs) {
+                return path;
+            }
+            return `${path}?${qs}`;
+        },
+    };
+};
+const errorResult = async (res) => {
+    let body = {
+        error: "unknown_error",
+        message: res.statusText || "Unknown error",
+    };
+    try {
+        const text = await res.text();
+        if (text.trim() !== "") {
+            try {
+                const maybeJson = JSON.parse(text);
+                body = {
+                    error: maybeJson.error ?? "unknown_error",
+                    message: maybeJson.message ?? (res.statusText || "Unknown error"),
+                };
+            }
+            catch {
+                body.message = text;
+            }
+        }
+    }
+    catch {
+        // Keep the HTTP status fallback when the body cannot be read.
+    }
+    return {
+        ok: false,
+        error: body,
+        status: res.status,
+        headers: res.headers,
+    };
+};
+const toSearchParams = (input) => {
+    if (input instanceof URLSearchParams) {
+        return input;
+    }
+    const params = new URLSearchParams();
+    for (const [key, raw] of Object.entries(input)) {
+        if (Array.isArray(raw)) {
+            for (const v of raw) {
+                appendQueryValue(params, key, v);
+            }
+            continue;
+        }
+        appendQueryValue(params, key, raw);
+    }
+    return params;
+};
+const appendQueryValue = (params, key, value) => {
+    if (value === undefined) {
+        return;
+    }
+    if (value === null) {
+        params.append(key, "null");
+        return;
+    }
+    params.append(key, String(value));
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createRsqlClient } from "./client.js";
+export { rsql } from "./default.js";
+export type { ApiErrorBody, ChangelogEntry, ColumnDefinition, CreateRsqlClientOptions, ImportFile, IndexCreateRequest, ListMeta, ListResponse, MutateOptions, NamespaceConfig, NamespaceDefinition, NamespaceModule, NamespaceOverview, NamespaceRecord, NamespacesModule, QueryInput, QueryRequest, QueryStatement, QueryValue, OverviewLatency, OverviewWindowName, RowsModule, RsqlClient, RsqlResult, SSEEvent, SSESubscribeOptions, SSESubscription, StorageSnapshot, TableCreateRequest, TableExportOptions, TableModule, TablesModule, TableUpdateRequest, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createRsqlClient } from "./client.js";
+export { rsql } from "./default.js";

package/dist/modules/namespace.d.ts

@@ -0,0 +1,3 @@
+import type { HttpClient } from "../http.js";
+import type { NamespaceModule } from "../types.js";
+export declare const createNamespaceModule: (http: HttpClient, namespace: string) => NamespaceModule;

package/dist/modules/namespace.js

@@ -0,0 +1,131 @@
+import { createTableModule } from "./table.js";
+import { createSSESubscription } from "./sse.js";
+const version = "v1";
+const jsonHeaders = {
+    "Content-Type": "application/json",
+};
+export const createNamespaceModule = (http, namespace) => {
+    const encoded = encodeURIComponent(namespace);
+    const base = `/${version}/${encoded}`;
+    return {
+        name: namespace,
+        tables: {
+            list() {
+                return http.json(`${base}/tables`);
+            },
+            create(request) {
+                return http.json(`${base}/tables`, {
+                    method: "POST",
+                    headers: jsonHeaders,
+                    body: JSON.stringify(request),
+                });
+            },
+            get(name) {
+                return http.json(`${base}/tables/${encodeURIComponent(name)}`);
+            },
+            update(name, request) {
+                return http.json(`${base}/tables/${encodeURIComponent(name)}`, {
+                    method: "PUT",
+                    headers: jsonHeaders,
+                    body: JSON.stringify(request),
+                });
+            },
+            delete(name, meta) {
+                if (!meta) {
+                    return http.empty(`${base}/tables/${encodeURIComponent(name)}`, {
+                        method: "DELETE",
+                    });
+                }
+                return http.empty(`${base}/tables/${encodeURIComponent(name)}`, {
+                    method: "DELETE",
+                    headers: jsonHeaders,
+                    body: JSON.stringify({ _meta: meta }),
+                });
+            },
+        },
+        table(name) {
+            return createTableModule(http, namespace, name);
+        },
+        query: {
+            run(request) {
+                return http.json(`${base}/query`, {
+                    method: "POST",
+                    headers: jsonHeaders,
+                    body: JSON.stringify(request),
+                });
+            },
+            batch(statements) {
+                return http.json(`${base}/query`, {
+                    method: "POST",
+                    headers: jsonHeaders,
+                    body: JSON.stringify({ statements }),
+                });
+            },
+        },
+        changelog: {
+            list(options) {
+                const path = http.withQuery(`${base}/changelog`, {
+                    table: options?.table,
+                    limit: options?.limit,
+                    offset: options?.offset,
+                });
+                return http.json(path);
+            },
+        },
+        overview: {
+            get(options) {
+                return http.json(http.withQuery(`${base}/overview`, { window: options?.window }));
+            },
+        },
+        events: {
+            async subscribe(options) {
+                const controller = new AbortController();
+                const externalSignal = options?.signal;
+                if (externalSignal) {
+                    if (externalSignal.aborted) {
+                        controller.abort(externalSignal.reason);
+                    }
+                    else {
+                        externalSignal.addEventListener("abort", () => {
+                            controller.abort(externalSignal.reason);
+                        }, { once: true });
+                    }
+                }
+                const path = http.withQuery(`${base}/subscribe`, {
+                    tables: options?.tables?.join(","),
+                });
+                const res = await http.raw(path, {
+                    method: "GET",
+                    signal: controller.signal,
+                    headers: {
+                        Accept: "text/event-stream",
+                    },
+                });
+                if (!res.ok) {
+                    return res;
+                }
+                try {
+                    const subscription = createSSESubscription(res.data, controller);
+                    return {
+                        ok: true,
+                        data: subscription,
+                        status: res.status,
+                        headers: res.headers,
+                    };
+                }
+                catch (err) {
+                    controller.abort();
+                    return {
+                        ok: false,
+                        error: {
+                            error: "invalid_sse_stream",
+                            message: err instanceof Error ? err.message : "SSE stream is not available",
+                        },
+                        status: 500,
+                        headers: res.headers,
+                    };
+                }
+            },
+        },
+    };
+};

package/dist/modules/namespaces.d.ts

@@ -0,0 +1,3 @@
+import type { HttpClient } from "../http.js";
+import type { NamespacesModule } from "../types.js";
+export declare const createNamespacesModule: (http: HttpClient) => NamespacesModule;

package/dist/modules/namespaces.js

@@ -0,0 +1,90 @@
+const version = "v1";
+const jsonHeaders = {
+    "Content-Type": "application/json",
+};
+export const createNamespacesModule = (http) => {
+    return {
+        create(request) {
+            const payload = {
+                ...request,
+                config: withDefaultNamespaceConfig(request.config),
+            };
+            return http.json(`/${version}/namespaces`, {
+                method: "POST",
+                headers: jsonHeaders,
+                body: JSON.stringify(payload),
+            });
+        },
+        list() {
+            return http.json(`/${version}/namespaces`);
+        },
+        get(name) {
+            return http.json(`/${version}/namespaces/${encodeURIComponent(name)}`);
+        },
+        update(name, config) {
+            return http.json(`/${version}/namespaces/${encodeURIComponent(name)}`, {
+                method: "PUT",
+                headers: jsonHeaders,
+                body: JSON.stringify({ config }),
+            });
+        },
+        delete(name) {
+            return http.empty(`/${version}/namespaces/${encodeURIComponent(name)}`, {
+                method: "DELETE",
+            });
+        },
+        duplicate(source, target) {
+            return http.json(`/${version}/namespaces/${encodeURIComponent(source)}/duplicate`, {
+                method: "POST",
+                headers: jsonHeaders,
+                body: JSON.stringify({ name: target }),
+            });
+        },
+        exportDb(name) {
+            return http.raw(`/${version}/namespaces/${encodeURIComponent(name)}/export`);
+        },
+        importDb(name, file) {
+            const formData = new FormData();
+            formData.set("file", toBlob(file.content, file.contentType), file.filename || "namespace.db");
+            return http.json(`/${version}/namespaces/${encodeURIComponent(name)}/import`, {
+                method: "POST",
+                body: formData,
+            });
+        },
+        importCsv(name, table, file) {
+            const formData = new FormData();
+            formData.set("file", toBlob(file.content, file.contentType ?? "text/csv"), file.filename || "rows.csv");
+            return http.json(`/${version}/namespaces/${encodeURIComponent(name)}/import?table=${encodeURIComponent(table)}`, {
+                method: "POST",
+                body: formData,
+            });
+        },
+    };
+};
+const withDefaultNamespaceConfig = (config) => {
+    const fallback = {
+        journal_mode: "wal",
+        busy_timeout: 5000,
+        query_timeout: 10000,
+        foreign_keys: true,
+        read_only: false,
+    };
+    return {
+        ...fallback,
+        ...(config ?? {}),
+    };
+};
+const toBlob = (content, contentType) => {
+    if (content instanceof Blob) {
+        return content;
+    }
+    if (typeof content === "string") {
+        return new Blob([content], { type: contentType });
+    }
+    if (content instanceof Uint8Array) {
+        const copy = new Uint8Array(content.byteLength);
+        copy.set(content);
+        return new Blob([copy.buffer], { type: contentType });
+    }
+    return new Blob([new Uint8Array(content)], { type: contentType });
+};

package/dist/modules/sse.d.ts

@@ -0,0 +1,2 @@
+import type { SSESubscription } from "../types.js";
+export declare const createSSESubscription: (response: Response, controller: AbortController) => SSESubscription;

package/dist/modules/sse.js

@@ -0,0 +1,68 @@
+export const createSSESubscription = (response, controller) => {
+    if (!response.body) {
+        throw new Error("SSE response body is not readable");
+    }
+    return {
+        response,
+        close: () => {
+            controller.abort();
+        },
+        stream: parseEventStream(response.body, controller.signal),
+    };
+};
+async function* parseEventStream(stream, signal) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let eventName = "message";
+    let dataLines = [];
+    try {
+        while (!signal.aborted) {
+            const { value, done } = await reader.read();
+            if (done) {
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            while (true) {
+                const idx = buffer.indexOf("\n");
+                if (idx === -1) {
+                    break;
+                }
+                const rawLine = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 1);
+                const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+                if (line === "") {
+                    if (dataLines.length > 0) {
+                        const rawData = dataLines.join("\n");
+                        dataLines = [];
+                        try {
+                            const parsed = JSON.parse(rawData);
+                            if (!parsed.action && eventName !== "message") {
+                                parsed.action = eventName;
+                            }
+                            yield parsed;
+                        }
+                        catch {
+                            // Ignore malformed event payloads.
+                        }
+                    }
+                    eventName = "message";
+                    continue;
+                }
+                if (line.startsWith(":")) {
+                    continue;
+                }
+                if (line.startsWith("event:")) {
+                    eventName = line.slice("event:".length).trim();
+                    continue;
+                }
+                if (line.startsWith("data:")) {
+                    dataLines.push(line.slice("data:".length).trim());
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/modules/table.d.ts

@@ -0,0 +1,3 @@
+import type { HttpClient } from "../http.js";
+import type { TableModule } from "../types.js";
+export declare const createTableModule: <Row extends Record<string, unknown>>(http: HttpClient, namespace: string, table: string) => TableModule<Row>;

package/dist/modules/table.js

@@ -0,0 +1,160 @@
+export const createTableModule = (http, namespace, table) => {
+    const ctx = {
+        http,
+        namespace: encodeURIComponent(namespace),
+        table: encodeURIComponent(table),
+    };
+    return {
+        rows: createRowsModule(ctx),
+        indexes: {
+            create(request) {
+                return ctx.http.json(`/${version}/${ctx.namespace}/tables/${ctx.table}/indexes`, {
+                    method: "POST",
+                    headers: jsonHeaders,
+                    body: JSON.stringify(request),
+                });
+            },
+            delete(indexName, meta) {
+                return deleteWithOptionalMeta(ctx.http, `/${version}/${ctx.namespace}/tables/${ctx.table}/indexes/${encodeURIComponent(indexName)}`, meta);
+            },
+        },
+        schema: {
+            get() {
+                return ctx.http.json(`/${version}/${ctx.namespace}/tables/${ctx.table}`);
+            },
+            update(request) {
+                return ctx.http.json(`/${version}/${ctx.namespace}/tables/${ctx.table}`, {
+                    method: "PUT",
+                    headers: jsonHeaders,
+                    body: JSON.stringify(request),
+                });
+            },
+            delete(meta) {
+                return deleteWithOptionalMeta(ctx.http, `/${version}/${ctx.namespace}/tables/${ctx.table}`, meta);
+            },
+        },
+        export(options) {
+            // The endpoint accepts the same filter grammar as rows.list. We add
+            // the required `format` (and optional `bom`) on top of the caller's
+            // own filters.
+            const query = { format: options.format };
+            if (options.bom) {
+                query.bom = "true";
+            }
+            const merged = mergeQuery(options.query, query);
+            const path = ctx.http.withQuery(`/${version}/${ctx.namespace}/tables/${ctx.table}/export`, merged);
+            return ctx.http.raw(path, { method: "GET" });
+        },
+    };
+};
+const mergeQuery = (base, extras) => {
+    const params = new URLSearchParams();
+    if (base instanceof URLSearchParams) {
+        for (const [k, v] of base.entries())
+            params.append(k, v);
+    }
+    else if (base) {
+        for (const [k, raw] of Object.entries(base)) {
+            const values = Array.isArray(raw) ? raw : [raw];
+            for (const v of values) {
+                if (v === undefined)
+                    continue;
+                params.append(k, v === null ? "null" : String(v));
+            }
+        }
+    }
+    for (const [k, v] of Object.entries(extras)) {
+        if (v === undefined || v === null)
+            continue;
+        params.set(k, String(v));
+    }
+    return params;
+};
+const createRowsModule = (ctx) => {
+    const basePath = `/${version}/${ctx.namespace}/tables/${ctx.table}/rows`;
+    return {
+        list(query) {
+            return ctx.http.json(ctx.http.withQuery(basePath, query));
+        },
+        insert(rows, options) {
+            const body = Array.isArray(rows) ? { rows } : { ...rows };
+            if (options?.meta) {
+                body._meta = options.meta;
+            }
+            return ctx.http.json(basePath, {
+                method: "POST",
+                headers: withPrefer(options?.prefer),
+                body: JSON.stringify(body),
+            });
+        },
+        get(id) {
+            return ctx.http.json(`${basePath}/${id}`);
+        },
+        update(id, payload, options) {
+            return ctx.http.json(`${basePath}/${id}`, {
+                method: "PUT",
+                headers: withPrefer(options?.prefer),
+                body: JSON.stringify(withMeta(payload, options?.meta)),
+            });
+        },
+        delete(id, options) {
+            return deleteWithPreferAndMeta(ctx.http, `${basePath}/${id}`, options);
+        },
+        bulkUpdate(query, payload, options) {
+            return ctx.http.json(ctx.http.withQuery(basePath, query), {
+                method: "PATCH",
+                headers: withPrefer(options?.prefer),
+                body: JSON.stringify(withMeta(payload, options?.meta)),
+            });
+        },
+        bulkDelete(query, options) {
+            return deleteWithPreferAndMeta(ctx.http, ctx.http.withQuery(basePath, query), options);
+        },
+    };
+};
+const deleteWithOptionalMeta = (http, path, meta) => {
+    if (!meta) {
+        return http.empty(path, { method: "DELETE" });
+    }
+    return http.empty(path, {
+        method: "DELETE",
+        headers: jsonHeaders,
+        body: JSON.stringify({ _meta: meta }),
+    });
+};
+const deleteWithPreferAndMeta = (http, path, options) => {
+    const headers = withPrefer(options?.prefer);
+    const body = options?.meta ? JSON.stringify({ _meta: options.meta }) : undefined;
+    if (options?.prefer === "return=representation") {
+        return http.json(path, {
+            method: "DELETE",
+            headers,
+            body,
+        });
+    }
+    return http.json(path, {
+        method: "DELETE",
+        headers,
+        body,
+    });
+};
+const withMeta = (payload, meta) => {
+    if (!meta) {
+        return payload;
+    }
+    return {
+        ...payload,
+        _meta: meta,
+    };
+};
+const withPrefer = (prefer) => {
+    const headers = new Headers(jsonHeaders);
+    if (prefer) {
+        headers.set("Prefer", prefer);
+    }
+    return headers;
+};
+const version = "v1";
+const jsonHeaders = {
+    "Content-Type": "application/json",
+};

package/dist/types.d.ts

@@ -0,0 +1,345 @@
+export interface ApiErrorBody {
+    error: string;
+    message: string;
+}
+export type RsqlResult<T> = {
+    ok: true;
+    data: T;
+    status: number;
+    headers: Headers;
+} | {
+    ok: false;
+    error: ApiErrorBody;
+    status: number;
+    headers: Headers;
+};
+export interface CreateRsqlClientOptions {
+    url: string;
+    token: string;
+    fetch?: typeof fetch;
+}
+export interface NamespaceConfig {
+    journal_mode: string;
+    busy_timeout: number;
+    max_db_size?: number;
+    query_timeout: number;
+    /** Optional. Omit to apply the server default (true). Send false to
+     *  explicitly disable foreign-key enforcement for the namespace. */
+    foreign_keys?: boolean;
+    read_only?: boolean;
+}
+export interface NamespaceDefinition {
+    name: string;
+    config?: NamespaceConfig;
+}
+export interface ColumnDefinition {
+    name: string;
+    type: string;
+    not_null?: boolean;
+    unique?: boolean;
+    default?: unknown;
+    index?: boolean;
+    pattern?: string;
+    max_length?: number;
+    min?: number;
+    max?: number;
+    auto?: boolean;
+    options?: string[];
+    formula?: string;
+    metadata?: Record<string, unknown>;
+    primary_key?: boolean;
+    read_only?: boolean;
+}
+export interface TableCreateRequest {
+    type: "table" | "view";
+    name: string;
+    metadata?: Record<string, unknown>;
+    columns?: ColumnDefinition[];
+    sql?: string;
+    /** Audit-meta passthrough. Wire key is `_meta` so it cannot collide with
+     *  a user-defined column named `meta`. */
+    _meta?: Record<string, unknown>;
+}
+export interface TableUpdateRequest {
+    rename?: string;
+    add_columns?: ColumnDefinition[];
+    drop_columns?: string[];
+    rename_columns?: Record<string, string>;
+    sql?: string;
+    metadata?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+export interface IndexCreateRequest {
+    type: "index" | "unique" | "fts";
+    name?: string;
+    columns: string[];
+    _meta?: Record<string, unknown>;
+}
+export interface ListMeta {
+    total_count: number;
+    filter_count: number;
+    limit: number;
+    offset: number;
+}
+export interface ListResponse<T> {
+    data: T[];
+    meta: ListMeta;
+}
+export interface QueryStatement {
+    sql: string;
+    params?: unknown[];
+}
+export interface QueryRequest {
+    sql?: string;
+    params?: unknown[];
+    statements?: QueryStatement[];
+}
+export interface ChangelogEntry {
+    id: number;
+    timestamp: string;
+    action: string;
+    table: string;
+    detail: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+export interface SSEEvent {
+    namespace?: string;
+    table: string;
+    action: string;
+    source_table?: string;
+    source_action?: string;
+    row?: Record<string, unknown>;
+    row_count?: number;
+    row_ids?: Array<string | number>;
+    detail?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+    timestamp: string;
+}
+export interface SSESubscribeOptions {
+    tables?: string[];
+    signal?: AbortSignal;
+}
+export interface SSESubscription {
+    stream: AsyncIterable<SSEEvent>;
+    response: Response;
+    close: () => void;
+}
+export type QueryInput = URLSearchParams | Record<string, QueryValue | QueryValue[]>;
+export type QueryValue = string | number | boolean | null | undefined;
+export interface MutateOptions {
+    prefer?: string;
+    meta?: Record<string, unknown>;
+}
+export interface ImportFile {
+    filename: string;
+    content: Blob | ArrayBuffer | Uint8Array | string;
+    contentType?: string;
+}
+export interface NamespaceRecord {
+    name: string;
+    created_at?: string;
+    db_path?: string;
+    config?: NamespaceConfig;
+    last_activity_at?: string;
+    storage?: StorageSnapshot;
+}
+export type OverviewWindowName = "1h" | "24h" | "7d" | "30d";
+export interface StorageSnapshot {
+    used_bytes: number;
+    allocated_bytes: number;
+    wal_bytes: number;
+    disk_bytes: number;
+}
+export interface OverviewLatency {
+    count: number;
+    average_ms: number;
+    p50_ms: number;
+    p95_ms: number;
+    p99_ms: number;
+}
+export interface NamespaceOverview {
+    generated_at: string;
+    window: {
+        name: OverviewWindowName;
+        from: string;
+        to: string;
+        resolution: "5m" | "1h";
+    };
+    health: {
+        status: "healthy" | "degraded";
+        mode: "read_write" | "read_only";
+        issues: string[];
+    };
+    storage: StorageSnapshot & {
+        reclaimable_bytes: number;
+        quota_bytes: number;
+        remaining_bytes: number | null;
+        usage_ratio: number | null;
+        database_file_bytes: number;
+        shm_bytes: number;
+    };
+    activity: {
+        requests: number;
+        reads: number;
+        writes: number;
+        errors: number;
+        error_rate: number;
+        response_bytes: number;
+        last_activity_at: string | null;
+        series: Array<{
+            timestamp: string;
+            reads: number;
+            writes: number;
+            errors: number;
+        }>;
+    };
+    read_latency: OverviewLatency;
+    write_latency: OverviewLatency;
+    write_contention: {
+        wait: OverviewLatency;
+        busy_errors: number;
+        timeouts: number;
+        quota_rejections: number;
+    };
+    schema: {
+        tables: number;
+        views: number;
+        indexes: number;
+        fts_indexes: number;
+    };
+    realtime: {
+        subscribers: number;
+    };
+    top_operations: Array<{
+        name: string;
+        count: number;
+        errors: number;
+        error_rate: number;
+        latency: OverviewLatency;
+    }>;
+    growth?: {
+        bytes_per_day: number;
+        sample_count: number;
+        projected_full_at: string | null;
+    };
+}
+export interface NamespacesModule {
+    create(request: NamespaceDefinition): Promise<RsqlResult<NamespaceRecord>>;
+    list(): Promise<RsqlResult<NamespaceRecord[]>>;
+    get(name: string): Promise<RsqlResult<NamespaceRecord>>;
+    update(name: string, config: NamespaceConfig): Promise<RsqlResult<NamespaceRecord>>;
+    delete(name: string): Promise<RsqlResult<void>>;
+    duplicate(source: string, target: string): Promise<RsqlResult<{
+        source: string;
+        target: string;
+    }>>;
+    /** Stream a consistent SQLite snapshot. The caller consumes response.body. */
+    exportDb(name: string): Promise<RsqlResult<Response>>;
+    importDb(name: string, file: ImportFile): Promise<RsqlResult<{
+        imported: boolean;
+        type: string;
+    }>>;
+    importCsv(name: string, table: string, file: ImportFile): Promise<RsqlResult<{
+        inserted: number;
+    }>>;
+}
+export interface TablesModule {
+    list(): Promise<RsqlResult<Array<Record<string, unknown>>>>;
+    create(request: TableCreateRequest): Promise<RsqlResult<{
+        created: string;
+        type: string;
+    }>>;
+    get(name: string): Promise<RsqlResult<Record<string, unknown>>>;
+    update(name: string, request: TableUpdateRequest): Promise<RsqlResult<{
+        updated: boolean;
+    }>>;
+    delete(name: string, meta?: Record<string, unknown>): Promise<RsqlResult<void>>;
+}
+export interface RowsModule<Row extends Record<string, unknown>> {
+    list(query?: QueryInput): Promise<RsqlResult<ListResponse<Row> | {
+        data: Row[];
+    }>>;
+    insert(rows: Partial<Row> | Array<Partial<Row>>, options?: MutateOptions): Promise<RsqlResult<{
+        data: Row[];
+    } | {
+        inserted: number;
+    }>>;
+    get(id: number): Promise<RsqlResult<Row>>;
+    update(id: number, payload: Record<string, unknown>, options?: MutateOptions): Promise<RsqlResult<{
+        data: Row[];
+    } | {
+        updated: number;
+    }>>;
+    delete(id: number, options?: MutateOptions): Promise<RsqlResult<{
+        data: Row[];
+    } | {
+        deleted: number;
+    } | void>>;
+    bulkUpdate(query: QueryInput, payload: Record<string, unknown>, options?: MutateOptions): Promise<RsqlResult<{
+        data: Row[];
+    } | {
+        updated: number;
+    }>>;
+    bulkDelete(query: QueryInput, options?: MutateOptions): Promise<RsqlResult<{
+        data: Row[];
+    } | {
+        deleted: number;
+    } | void>>;
+}
+export interface TableExportOptions {
+    format: "csv";
+    /** Filter / select / order / search params, identical to rows.list. */
+    query?: QueryInput;
+    /** Prepend the UTF-8 BOM (0xEF 0xBB 0xBF) for Excel compatibility. */
+    bom?: boolean;
+}
+export interface TableModule<Row extends Record<string, unknown>> {
+    rows: RowsModule<Row>;
+    indexes: {
+        create(request: IndexCreateRequest): Promise<RsqlResult<{
+            created: boolean;
+        }>>;
+        delete(indexName: string, meta?: Record<string, unknown>): Promise<RsqlResult<void>>;
+    };
+    schema: {
+        get(): Promise<RsqlResult<Record<string, unknown>>>;
+        update(request: TableUpdateRequest): Promise<RsqlResult<{
+            updated: boolean;
+        }>>;
+        delete(meta?: Record<string, unknown>): Promise<RsqlResult<void>>;
+    };
+    /**
+     * Stream the table contents in the requested format. Returns the underlying
+     * Response so callers can decide how to consume the body (text(), blob(),
+     * getReader(), pipe to disk).
+     */
+    export(options: TableExportOptions): Promise<RsqlResult<Response>>;
+}
+export interface NamespaceModule {
+    readonly name: string;
+    tables: TablesModule;
+    table<Row extends Record<string, unknown> = Record<string, unknown>>(name: string): TableModule<Row>;
+    query: {
+        run(request: QueryRequest): Promise<RsqlResult<Record<string, unknown>>>;
+        batch(statements: QueryStatement[]): Promise<RsqlResult<Record<string, unknown>>>;
+    };
+    changelog: {
+        list(options?: {
+            table?: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<RsqlResult<ChangelogEntry[]>>;
+    };
+    overview: {
+        get(options?: {
+            window?: OverviewWindowName;
+        }): Promise<RsqlResult<NamespaceOverview>>;
+    };
+    events: {
+        subscribe(options?: SSESubscribeOptions): Promise<RsqlResult<SSESubscription>>;
+    };
+}
+export interface RsqlClient {
+    namespaces: NamespacesModule;
+    ns(name: string): NamespaceModule;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@k2b/rsql",
+  "version": "0.4.0",
+  "description": "Type-safe fetch client for rsql",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k2b-dev/rsql.git",
+    "directory": "client"
+  },
+  "homepage": "https://github.com/k2b-dev/rsql#readme",
+  "bugs": {
+    "url": "https://github.com/k2b-dev/rsql/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bunx tsc -p tsconfig.build.json",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test ./tests",
+    "test:package": "./scripts/test-package.sh",
+    "test:e2e": "bun test ./tests/e2e.test.ts",
+    "test:perf": "bun test ./tests/performance.test.ts",
+    "perf:fast": "bun run ./perf/cli.ts fast",
+    "perf:deep": "bun run ./perf/cli.ts deep",
+    "perf:report": "bun run ./perf/cli.ts report",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "packageManager": "bun@1.3.14"
+}