@crvouga/mockingbird-service-sqlite 1.2.1 → 2.0.0

package/dist/socket/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A small TCP server in front of the in-memory SQLite engine.
+ *
+ * SQLite has no client/server wire protocol, so the stock `sqlite3` CLI cannot
+ * attach. This entry speaks a length-prefixed JSON frame (`uint32` big-endian
+ * length, then UTF-8 JSON, at most 8 MiB) and ships an in-package `connect(uri)`
+ * client. URIs look like `sqlite://127.0.0.1:5432/app`. It needs `node:net`, so
+ * it stays out of the browser build. Portable queries go through `POST /sql/query`
+ * on the admin API.
+ *
+ * @example
+ * ```ts
+ * import { connect, serve } from "@crvouga/mockingbird-service-sqlite/socket";
+ *
+ * const server = await serve("sqlite://127.0.0.1:0/app");
+ * const db = await connect(server.url);
+ * await db.exec("CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)");
+ * await db.close();
+ * await server.close();
+ * ```
+ *
+ * @module
+ */
+import { type Server } from "node:net";
+import { Database, type DatabaseOptions } from "../api/database.js";
+export type SocketServeOptions = {
+    /** TCP port. `0` (the default) picks a free one. */
+    port?: number;
+    /** Interface to bind. Default `127.0.0.1`. */
+    host?: string;
+    /** Engine to share. Omit for a fresh deterministic database. */
+    database?: Database;
+    databaseOptions?: DatabaseOptions;
+    /** When set, a frame naming another database is rejected. */
+    databaseName?: string;
+    /** `sqlite://host:port/name`. An omitted port means `0` (ephemeral) for the server. */
+    url?: string;
+};
+export type SqliteServer = {
+    readonly port: number;
+    readonly host: string;
+    /** Bound `sqlite://` URI. */
+    readonly url: string;
+    readonly database: Database;
+    readonly server: Server;
+    close(): Promise<void>;
+};
+export type SqliteSocket = {
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    exec(sql: string): Promise<{
+        changes: number;
+    }>;
+    close(): Promise<void>;
+};
+/** Start a server and resolve once it is listening. A string argument is a `sqlite://` URI. */
+export declare const serve: (input?: SocketServeOptions | string) => Promise<SqliteServer>;
+/** Open a client for a `sqlite://host:port/name` URI. The port must already be listening. */
+export declare const connect: (uri: string) => Promise<SqliteSocket>;