@zukhruf/sqlite-federation 0.0.0-stage → 0.3.31

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+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

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# @zukhruf/sqlite-federation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A host keeps its data in many SQLite databases, for example one database for each data source. A statement must read some of them together, for example to join messages with contacts. One SQLite connection can attach at most 10 databases, and the SQLite in Node cannot raise that limit. This package gives one read-only handle over a primary database and every additional database that the host can locate. The primary database stays open for the lifetime of the handle. Each statement attaches the additional databases it names and detaches them when it ends. This is also known as query federation: one query reads many separate databases.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Use it
+
+This project is an experiment. It uses only `node:sqlite`.
+
+```sh
+npm install @zukhruf/sqlite-federation
+```
+
+## Read many databases with one handle
+
+The host gives `locate`. A statement names each database as a schema.
+
+```ts
+import { mkdtempDisposable } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+import { Federation } from '@zukhruf/sqlite-federation';
+
+await using scratch = await mkdtempDisposable(join(tmpdir(), 'federation-'));
+const messagesPath = join(scratch.path, 'messages.sqlite');
+const contactsPath = join(scratch.path, 'contacts.sqlite');
+{
+  using messages = new DatabaseSync(messagesPath);
+  messages.exec(`CREATE TABLE messages (handle TEXT, text TEXT);
+    INSERT INTO messages VALUES ('+962790000000', 'See you at 6');`);
+  using contacts = new DatabaseSync(contactsPath);
+  contacts.exec(`CREATE TABLE contacts (phone TEXT, name TEXT);
+    INSERT INTO contacts VALUES ('+962790000000', 'Sara');`);
+}
+const paths = new Map([
+  ['messages', messagesPath],
+  ['contacts', contactsPath],
+]);
+
+using federation = new Federation({
+  main: ':memory:',
+  locate: (name) => paths.get(name),
+});
+console.log(federation.sql.all`
+  SELECT c.name, m.text
+  FROM messages.messages m JOIN contacts.contacts c ON c.phone = m.handle`);
+```
+
+Output:
+
+```
+[ [Object: null prototype] { name: 'Sara', text: 'See you at 6' } ]
+```
+
+- `sql` has `all` and `get` of the `SQLTagStore` of `node:sqlite`. A value in `${}` is a bound parameter.
+- `main` is a primary database path or `{ name }` to find that path through `locate`. It is opened read-only for the lifetime of the handle. Use `':memory:'` when there is no primary file. `main` does not count toward the attachment limit.
+- A statement names each additional database as a schema: `messages.messages`. Use unqualified names for the primary database and temporary views; qualify cross-database tables. There is no pre-attached search path for unqualified source tables.
+- `locate(name)` is required. It returns the path of a database, or `undefined` when the host has no database by that name. The constructor calls it once for a named `main`; each statement calls it for additional databases, so it reads them from their new paths after the host moves them.
+- Return `undefined` for a database that the host has not written yet. The handle cannot make a database, so an attach of a path with no file fails.
+- Additional databases are read-only. A statement that writes to one fails with `attempt to write a readonly database`. Connection-local temporary objects remain writable.
+- `using` closes the connection of the handle at the end of its scope.
+
+## Load temporary views and run SQL strings
+
+`exec(sql)` executes connection-local setup SQL, including a file containing several `CREATE TEMP VIEW` statements. It uses SQLite's `exec` directly, without replaying the script. The databases a temporary view refers to are resolved when a query reads it.
+
+`query(sql)` runs exactly one SQL statement and returns `QueryResult`: `columns`, including headings when there are no rows, and `rows`, whose values are indexed by column position. Duplicate column names therefore keep both values. Trailing comments and empty statements are allowed; a second statement, even malformed, fails before the first executes.
+
+```ts
+federation.exec(`
+  CREATE TEMP VIEW conversations AS
+  SELECT c.name, m.text
+  FROM messages.messages m JOIN contacts.contacts c ON c.phone = m.handle;
+`);
+const result = federation.query('SELECT * FROM conversations');
+```
+
+Qualified tables and PRAGMAs discover additional databases through `locate`. Both `PRAGMA contacts.table_info(contacts)` and `SELECT * FROM pragma_table_info('contacts', 'contacts')` locate Contacts, including when the schema is a bound parameter in a tagged query. Quoted schema names such as `"call-history"` work too. Every attachment made for the statement is detached afterwards, including on failure; `main` and temporary views remain on the connection. The additional databases count toward the attachment limit.
+
+The constructor accepts Node's `timeout` option for waiting on a writer's lock, in milliseconds. Omit it to use Node's native behavior. Hosts that need crash recovery perform it before supplying the paths, including inside `locate` for a named primary or additional database; Federation opens those files read-only.
+
+## Read a primary database
+
+Supply `main: { name }` to find the primary database through `locate`, or supply its path directly. Tables can be qualified with `main`, and unqualified schema queries and PRAGMAs describe that database. A named primary is opened as `main`, not attached under its name. Presets loaded with `exec` live on the same connection and can be joined with attached databases. Federation closes the connection on disposal.
+
+```ts
+import { Federation } from '@zukhruf/sqlite-federation';
+
+using database = new Federation({
+  main: { name: 'messages' },
+  locate: (name) => paths.get(name),
+  timeout: 30_000,
+});
+const result = database.query(
+  'SELECT c.name, m.text FROM main.messages m JOIN contacts.contacts c ON c.phone = m.handle',
+);
+```
+
+## Each statement attaches what it names
+
+- SQLite fails with `no such table: <name>.<table>` for a qualified table or `unknown database <name>` for a PRAGMA when its database is not attached. The handle decodes the name, attaches that database and runs the statement again. It never parses the statement. [ADR 0002](./docs/adr/0002-the-error-of-sqlite-names-the-database.md) tells why.
+- When the statement ends, the handle detaches each database that it attached, also when the statement fails. An attach costs less than 1 ms. [ADR 0001](./docs/adr/0001-each-statement-attaches-what-it-names.md) tells why.
+- Between two statements, the handle holds no lock. A writer in another connection or process can commit.
+- One statement can attach at most 10 databases in addition to `main`. To read more, split the statement and join the rows in code. [ADR 0003](./docs/adr/0003-a-statement-over-the-limit-fails.md) tells why.
+
+## Errors
+
+| Error                                  | When                                                                                                                                              |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TooManyDatabasesError`                | A statement names more databases than the limit. `names` has at least one name more than the limit. The message tells you to split the statement. |
+| `Unknown main database <name>`         | The constructor cannot locate the named primary database.                                                                                         |
+| `no such table: <name>.<table>`        | The error of SQLite, when `locate` returns `undefined` for the name, or when the database does not have the table.                                |
+| `unable to open database file`         | The error of SQLite, when `locate` returns a path with no file.                                                                                   |
+| `attempt to write a readonly database` | The error of SQLite, when a statement writes.                                                                                                     |
+| The error of `locate`                  | The constructor or statement fails with that error. The databases that the statement attached before are detached.                                |
+| `unknown database <name>`              | The error of SQLite, when a PRAGMA names a database that `locate` cannot find. Quoting follows the statement or the table-valued PRAGMA argument. |
+| `Run one SQL statement at a time`      | A raw query contains a second statement.                                                                                                          |
+
+## The same concepts in other systems
+
+| System                    | What it does                                                                                                                                                                          |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite `swarmvtab`        | A virtual table over one table in many databases. It opens each database on its own connection and closes the least recently used one. It is an extension that Node does not include. |
+| Datasette `--crossdb`     | It attaches the first 10 databases and ignores the others.                                                                                                                            |
+| `q` (harelba/q)           | It attaches databases up to the limit, and copies the tables of the others into a temporary database.                                                                                 |
+| PostgreSQL `postgres_fdw` | A foreign table reads a table of another server, and one query can join it with local tables.                                                                                         |
+
+## Documentation
+
+- [0001 Each statement attaches what it names](./docs/adr/0001-each-statement-attaches-what-it-names.md)
+- [0002 The error of SQLite names the database](./docs/adr/0002-the-error-of-sqlite-names-the-database.md)
+- [0003 A statement over the limit fails](./docs/adr/0003-a-statement-over-the-limit-fails.md)
+
+## Development
+
+This package is part of the [zukhruf](../../../README.md) workspace. Run the commands from the workspace root.
+
+```sh
+npm install
+npx nx run sqlite-federation:test        # builds, then runs the tests in src/
+npx nx run sqlite-federation:typecheck   # formats, lints, then type checks
+npx nx run sqlite-federation:build       # compiles src/ to dist/
+```
+
+```
+src/
+  index.ts                       the exports
+  federation.ts                  Federation, FederationOptions, Query, QueryResult and Locate
+  too-many-databases-error.ts    TooManyDatabasesError
+  federation.test.ts             the tests, on real SQLite files
+```

package/dist/federation.d.ts

@@ -0,0 +1,22 @@
+import { type DatabaseSyncOptions, type SQLOutputValue, type SQLTagStore } from 'node:sqlite';
+export type Query = Pick<SQLTagStore, 'all' | 'get'>;
+export type QueryResult = {
+    readonly columns: readonly string[];
+    readonly rows: readonly Readonly<Record<number, SQLOutputValue>>[];
+};
+export type Locate = (name: string) => string | undefined;
+export type FederationOptions = Pick<DatabaseSyncOptions, 'timeout'> & {
+    readonly main: string | {
+        readonly name: string;
+    };
+    readonly locate: Locate;
+};
+export declare class Federation implements Disposable {
+    #private;
+    readonly sql: Query;
+    constructor({ main, locate, ...options }: FederationOptions);
+    exec(sql: string): void;
+    query(sql: string): QueryResult;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=federation.d.ts.map

package/dist/federation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../src/federation.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAMrB,MAAM,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AAGrD,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC;AAIF,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,GAAG;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAKF,qBAAa,UAAW,YAAW,UAAU;;IAC3C,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC;gBAIR,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,iBAAiB;IAuB3D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOvB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAqD/B,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB"}

package/dist/federation.js

@@ -0,0 +1,114 @@
+import { DatabaseSync, } from 'node:sqlite';
+import { TooManyDatabasesError } from "./too-many-databases-error.js";
+// One read-only handle over main and every database the host can locate, past
+// the limit on how many one SQLite connection attaches at once. Main stays
+// open; each statement attaches and detaches the additional databases it names.
+export class Federation {
+    sql;
+    #connection;
+    #locate;
+    constructor({ main, locate, ...options }) {
+        this.#locate = locate;
+        if (typeof main !== 'string') {
+            const path = locate(main.name);
+            if (path === undefined)
+                throw new Error(`Unknown main database ${main.name}`);
+            main = path;
+        }
+        this.#connection = new DatabaseSync(main, {
+            ...options,
+            readOnly: true,
+        });
+        const store = this.#connection.createTagStore();
+        this.sql = {
+            all: (strings, ...values) => this.#statement(() => store.all(strings, ...values)),
+            get: (strings, ...values) => this.#statement(() => store.get(strings, ...values)),
+        };
+    }
+    // Loads connection-local SQL, such as a file defining temporary views.
+    // SQLite resolves the databases those views name when a query reads them.
+    exec(sql) {
+        this.#connection.exec(sql);
+    }
+    // Runs one SQL string, discovering additional databases from qualified names.
+    // SQLite judges the tail: comments and empty statements are allowed, but a
+    // second statement, even malformed, is rejected before the first executes.
+    query(sql) {
+        return this.#statement(() => {
+            const statement = this.#connection.prepare(sql);
+            let another;
+            try {
+                this.#connection.prepare(sql.slice(statement.sourceSQL.length));
+                another = true;
+            }
+            catch (error) {
+                another = !(error instanceof Error &&
+                    'code' in error &&
+                    error.code === 'ERR_INVALID_ARG_VALUE');
+            }
+            if (another)
+                throw new Error('Run one SQL statement at a time');
+            statement.setReturnArrays(true);
+            return {
+                columns: statement.columns().map(({ name }) => name),
+                rows: statement.all(),
+            };
+        });
+    }
+    // SQLite says which database is missing, so the statement is never parsed
+    // here. A name the host cannot locate, or a table its database lacks, fails
+    // as the statement would. No additional database stays attached, so the next
+    // statement asks the host again where each additional database is.
+    #statement(run) {
+        const attached = [];
+        try {
+            for (;;) {
+                try {
+                    return run();
+                }
+                catch (error) {
+                    const name = missingDatabase(error);
+                    if (name === undefined || attached.includes(name))
+                        throw error;
+                    const path = this.#locate(name);
+                    if (path === undefined)
+                        throw error;
+                    const { attach: limit } = this.#connection.limits;
+                    if (attached.length === limit)
+                        throw new TooManyDatabasesError(limit, [...attached, name]);
+                    this.#connection
+                        .prepare(`ATTACH DATABASE ? AS ${quoted(name)}`)
+                        .run(path);
+                    attached.push(name);
+                }
+            }
+        }
+        finally {
+            for (const name of attached)
+                this.#connection.exec(`DETACH DATABASE ${quoted(name)}`);
+        }
+    }
+    [Symbol.dispose]() {
+        this.#connection.close();
+    }
+}
+// Table errors name the schema directly. PRAGMA errors carry a SQL token:
+// SQLite preserves identifier quoting, and table-valued PRAGMAs quote it
+// as a string. Decode that token, without parsing the statement itself.
+function missingDatabase(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const token = /^unknown database (.+)$/s.exec(error.message)?.[1];
+    if (token === undefined)
+        return /^no such table: ([^.]+)\./.exec(error.message)?.[1];
+    const quote = token[0];
+    if (quote === '[')
+        return token.slice(1, -1);
+    if (quote === '"' || quote === "'" || quote === '`')
+        return token.slice(1, -1).replaceAll(quote + quote, quote);
+    return token;
+}
+function quoted(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+//# sourceMappingURL=federation.js.map

package/dist/federation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation.js","sourceRoot":"","sources":["../src/federation.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Federation, type FederationOptions, type Locate, type Query, type QueryResult, } from './federation.ts';
+export { TooManyDatabasesError } from './too-many-databases-error.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,MAAM,EACX,KAAK,KAAK,EACV,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Federation, } from "./federation.js";
+export { TooManyDatabasesError } from "./too-many-databases-error.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,GAKX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/too-many-databases-error.d.ts

@@ -0,0 +1,5 @@
+export declare class TooManyDatabasesError extends Error {
+    readonly names: readonly string[];
+    constructor(limit: number, names: readonly string[]);
+}
+//# sourceMappingURL=too-many-databases-error.d.ts.map

package/dist/too-many-databases-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"too-many-databases-error.d.ts","sourceRoot":"","sources":["../src/too-many-databases-error.ts"],"names":[],"mappings":"AACA,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEtB,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE;CAOpD"}

package/dist/too-many-databases-error.js

@@ -0,0 +1,10 @@
+// One statement names more databases than one SQLite connection can attach.
+export class TooManyDatabasesError extends Error {
+    names;
+    constructor(limit, names) {
+        super(`One statement can read at most ${limit} databases, and this one names at least ${names.length}: ${names.join(', ')}. Split it into statements that each name ${limit} or fewer, and join their rows in code.`);
+        this.name = 'TooManyDatabasesError';
+        this.names = names;
+    }
+}
+//# sourceMappingURL=too-many-databases-error.js.map

package/dist/too-many-databases-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"too-many-databases-error.js","sourceRoot":"","sources":["../src/too-many-databases-error.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,KAAK,CAAoB;IAElC,YAAY,KAAa,EAAE,KAAwB;QACjD,KAAK,CACH,kCAAkC,KAAK,2CAA2C,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,6CAA6C,KAAK,yCAAyC,CAC/M,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@zukhruf/sqlite-federation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.31",
+  "description": "One read-only handle over many SQLite databases. Each statement attaches the databases that it names and detaches them when it ends. Thus a host can keep more databases than the attach limit of SQLite, and one statement can read up to 10 of them in addition to the primary database.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/sqlite/federation"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/sqlite/federation#readme",
+  "keywords": [
+    "sqlite",
+    "node-sqlite",
+    "attach",
+    "federation",
+    "federated-query",
+    "multi-database",
+    "read-only"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zukhruf/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}