@cogenta/core 0.1.0

package/dist/db/dialect.js

@@ -0,0 +1,147 @@
+import { CogentaError } from '../errors/index.js';
+const RAW = Symbol('cogenta.sql.raw');
+function isRaw(value) {
+    return typeof value === 'object' && value !== null && RAW in value;
+}
+function isFragment(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'parts' in value &&
+        'values' in value &&
+        Array.isArray(value.parts));
+}
+/** Tagged template for SQL. Interpolated values are always bound, never inlined. */
+export function sql(strings, ...values) {
+    const parts = [];
+    const bound = [];
+    let current = strings[0] ?? '';
+    for (const [index, value] of values.entries()) {
+        const next = strings[index + 1] ?? '';
+        if (isRaw(value)) {
+            current += value[RAW] + next;
+        }
+        else if (isFragment(value)) {
+            // Nested fragment: splice its text and values into this one.
+            current += value.parts[0] ?? '';
+            for (const [nestedIndex, nestedValue] of value.values.entries()) {
+                parts.push(current);
+                bound.push(nestedValue);
+                current = value.parts[nestedIndex + 1] ?? '';
+            }
+            current += next;
+        }
+        else {
+            parts.push(current);
+            bound.push(value);
+            current = next;
+        }
+    }
+    parts.push(current);
+    return { parts, values: bound };
+}
+/**
+ * Text inserted verbatim, with no binding.
+ *
+ * Only ever for SQL the code itself wrote. A value that reached the process from
+ * outside must go through `sql` so it is bound — this is the one function in the
+ * layer that can produce an injection, and it is named to say so.
+ */
+export function unsafeRaw(text) {
+    return sql `${{ [RAW]: text }}`;
+}
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Quotes a table or column name for the dialect. Postgres and SQLite use double
+ * quotes, MySQL uses backticks.
+ */
+export function identifier(name, dialect) {
+    if (!IDENTIFIER.test(name)) {
+        throw new CogentaError({
+            code: 'DB_DIALECT_UNSUPPORTED',
+            message: `"${name}" is not a usable SQL identifier.`,
+            hint: 'Table and column names must start with a letter or underscore and contain only letters, digits and underscores.',
+            details: { name },
+        });
+    }
+    return unsafeRaw(dialect === 'mysql' ? `\`${name}\`` : `"${name}"`);
+}
+/**
+ * Adapts a bound value to what the driver for this dialect accepts.
+ *
+ * SQLite has no boolean and no date type, so `true` and a `Date` have to become
+ * an integer and a string. Doing it here, once, is what stops every call site
+ * from having to know which database it is talking to.
+ */
+export function encodeValue(value, dialect) {
+    if (value === undefined)
+        return null;
+    if (typeof value === 'boolean') {
+        return dialect === 'postgres' ? value : Number(value);
+    }
+    if (value instanceof Date) {
+        // A timestamp is stored in UTC everywhere. MySQL has no time zone on
+        // `datetime`, so it gets a UTC string rather than an offset it would drop.
+        if (dialect === 'postgres')
+            return value;
+        if (dialect === 'mysql')
+            return value.toISOString().slice(0, 19).replace('T', ' ');
+        return value.toISOString();
+    }
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value !== null && typeof value === 'object' && !Buffer.isBuffer(value)) {
+        // Objects and arrays are stored as JSON text. Postgres would accept a native
+        // array here, but only for some column types, and the difference is not
+        // worth exposing.
+        return JSON.stringify(value);
+    }
+    return value;
+}
+/** Renders a fragment into the exact string and parameters this dialect expects. */
+export function compile(fragment, dialect) {
+    let text = fragment.parts[0] ?? '';
+    const params = [];
+    for (const [index, value] of fragment.values.entries()) {
+        params.push(encodeValue(value, dialect));
+        text += dialect === 'postgres' ? `$${params.length}` : '?';
+        text += fragment.parts[index + 1] ?? '';
+    }
+    return { text, params };
+}
+/**
+ * Statements that hand back rows: a read, or a write with `RETURNING`.
+ *
+ * Shared by every driver so `rows` and `rowsAffected` mean the same thing on all
+ * three dialects. Left to each driver, Postgres would report a `SELECT` of two
+ * rows as "two rows affected" while SQLite reported zero — the kind of quiet
+ * divergence the contract suite exists to prevent.
+ */
+export function returnsRows(text) {
+    return READ_STATEMENT.test(text) || RETURNING_CLAUSE.test(text);
+}
+/** True when the statement creates, changes or removes rows. */
+export function isWrite(text) {
+    return !READ_STATEMENT.test(text);
+}
+const READ_STATEMENT = /^[\s(]*(?:select|with|pragma|explain|show|values|describe)\b/i;
+const RETURNING_CLAUSE = /\breturning\b/i;
+/**
+ * Renders a `LIMIT` count as a literal rather than a bound parameter.
+ *
+ * MySQL prepared statements reject a placeholder there — `LIMIT ?` fails with
+ * "Incorrect arguments to mysqld_stmt_execute". Rather than encode that as one
+ * more dialect difference for callers to remember, the count is inlined
+ * everywhere. It is validated as a non-negative integer first, so inlining it
+ * cannot inject: this is the only place a number reaches the SQL text directly.
+ */
+export function limit(count) {
+    if (!Number.isSafeInteger(count) || count < 0) {
+        throw new CogentaError({
+            code: 'DB_DIALECT_UNSUPPORTED',
+            message: `A LIMIT must be a non-negative whole number, received ${String(count)}.`,
+            hint: 'Pass a plain integer, such as the batch size of a worker.',
+        });
+    }
+    return unsafeRaw(String(count));
+}
+//# sourceMappingURL=dialect.js.map

package/dist/db/dialect.js.map

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

package/dist/db/drizzle.d.ts

@@ -0,0 +1,35 @@
+import type { DrizzleConfig } from 'drizzle-orm';
+import { type MySqlRemoteDatabase } from 'drizzle-orm/mysql-proxy';
+import { type PgRemoteDatabase } from 'drizzle-orm/pg-proxy';
+import { type SqliteRemoteDatabase } from 'drizzle-orm/sqlite-proxy';
+import type { DatabaseHandle, SqlExecutor, TransactionOptions } from './types.js';
+export type { MySqlRemoteDatabase, PgRemoteDatabase, SqliteRemoteDatabase };
+/**
+ * Runs Drizzle work inside a handle transaction, on every dialect.
+ *
+ * Replaces `db.transaction()`, which a proxy instance cannot provide. The
+ * instance is rebuilt on the transaction's executor, so every statement it
+ * issues lands on the connection the transaction is pinned to — and rolls back
+ * with it. `{ immediate: true }` still means what it means on SQLite: take the
+ * write lock at `BEGIN`, which any read-modify-write needs.
+ */
+export declare function drizzleTransaction<TDrizzle, T>(handle: DatabaseHandle, create: (tx: SqlExecutor) => TDrizzle, run: (db: TDrizzle) => Promise<T>, options?: TransactionOptions): Promise<T>;
+/**
+ * Drizzle over a SQLite handle, or over the `tx` executor of one.
+ *
+ * Declare tables with `sqliteTable`.
+ */
+export declare function createSqliteDrizzle<TSchema extends Record<string, unknown> = Record<string, never>>(executor: SqlExecutor, config?: DrizzleConfig<TSchema>): SqliteRemoteDatabase<TSchema>;
+/**
+ * Drizzle over a Postgres handle, or over the `tx` executor of one.
+ *
+ * Declare tables with `pgTable`.
+ */
+export declare function createPostgresDrizzle<TSchema extends Record<string, unknown> = Record<string, never>>(executor: SqlExecutor, config?: DrizzleConfig<TSchema>): PgRemoteDatabase<TSchema>;
+/**
+ * Drizzle over a MySQL or MariaDB handle, or over the `tx` executor of one.
+ *
+ * Declare tables with `mysqlTable`.
+ */
+export declare function createMysqlDrizzle<TSchema extends Record<string, unknown> = Record<string, never>>(executor: SqlExecutor, config?: DrizzleConfig<TSchema>): MySqlRemoteDatabase<TSchema>;
+//# sourceMappingURL=drizzle.d.ts.map

package/dist/db/drizzle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../src/db/drizzle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC3F,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACxF,OAAO,EAA4B,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAG9F,OAAO,KAAK,EAAmB,cAAc,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAElG,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAA;AAyD3E;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,CAAC,EAClD,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,QAAQ,EACrC,GAAG,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,EACjC,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC/D,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAevF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC/D,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAYnF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAChG,QAAQ,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,GAC9B,mBAAmB,CAAC,OAAO,CAAC,CAsB9B"}

package/dist/db/drizzle.js

@@ -0,0 +1,128 @@
+import { drizzle as drizzleMysql } from 'drizzle-orm/mysql-proxy';
+import { drizzle as drizzlePostgres } from 'drizzle-orm/pg-proxy';
+import { drizzle as drizzleSqlite } from 'drizzle-orm/sqlite-proxy';
+import { CogentaError } from '../errors/index.js';
+import { returnsRows } from './dialect.js';
+/**
+ * Drizzle on top of a `DatabaseHandle`, through Drizzle's proxy drivers.
+ *
+ * Every dialect goes through the proxy rather than through the driver Drizzle
+ * ships for it, for one reason: a proxy runs its SQL on **our** connection.
+ * That keeps a single pool, our transaction pinning, our typed errors and our
+ * "no parameters in the error" rule for ORM traffic as well as for raw SQL.
+ *
+ * The alternative was measured, not assumed. `drizzle-orm/postgres-js` takes the
+ * postgres.js client and rewrites `client.options.serializers` for every date
+ * type on it; the handle then shares a client that can no longer bind a `Date`
+ * — `insert … values ($1)` fails with "The string argument must be of type
+ * string". Handing Drizzle its own client instead would double the connection
+ * count on hosting that allows very few. On SQLite the question does not arise:
+ * `better-sqlite3` is forbidden by rule R10 and `node:sqlite` has no Drizzle
+ * driver, so the proxy is the only door.
+ *
+ * What it costs, in exchange:
+ *
+ * - `db.transaction()` on the returned instance is unusable. The Postgres and
+ *   MySQL proxies throw by design, and on SQLite Drizzle would issue `begin` and
+ *   `commit` as separate statements, each taking and releasing the handle's file
+ *   lock, so a concurrent write could slip inside the transaction and be rolled
+ *   back with it. Use `handle.transaction()` and build an instance on the `tx`
+ *   executor — see `drizzleTransaction`.
+ * - No streaming and no `db.batch()`: both need a driver-level feature the proxy
+ *   contract does not carry.
+ */
+/**
+ * Drizzle maps a result row by position, so the proxy must hand it the column
+ * values in order rather than an object — a join selects `users.id` and
+ * `posts.id`, and one of the two disappears from an object.
+ */
+const AS_ARRAYS = { asArrays: true };
+/**
+ * Drizzle types the callback as always returning rows, but `get` on an empty
+ * result must hand back nothing at all: an empty array would be mapped into a
+ * row whose every column is `undefined`, and `db.get()` would answer with an
+ * object instead of nothing. The cast states that exception in one place.
+ */
+const NO_ROW = undefined;
+function assertDialect(executor, expected) {
+    if (executor.dialect === expected)
+        return;
+    throw new CogentaError({
+        code: 'DB_DIALECT_UNSUPPORTED',
+        message: `This Drizzle instance writes ${expected} SQL, but the connection speaks ${executor.dialect}.`,
+        hint: `Build it with the factory for ${executor.dialect}, and declare the schema with that dialect's table builder.`,
+        details: { expected, actual: executor.dialect },
+    });
+}
+/**
+ * Runs Drizzle work inside a handle transaction, on every dialect.
+ *
+ * Replaces `db.transaction()`, which a proxy instance cannot provide. The
+ * instance is rebuilt on the transaction's executor, so every statement it
+ * issues lands on the connection the transaction is pinned to — and rolls back
+ * with it. `{ immediate: true }` still means what it means on SQLite: take the
+ * write lock at `BEGIN`, which any read-modify-write needs.
+ */
+export async function drizzleTransaction(handle, create, run, options) {
+    return handle.transaction(async (tx) => run(create(tx)), options);
+}
+/**
+ * Drizzle over a SQLite handle, or over the `tx` executor of one.
+ *
+ * Declare tables with `sqliteTable`.
+ */
+export function createSqliteDrizzle(executor, config) {
+    assertDialect(executor, 'sqlite');
+    return drizzleSqlite(async (text, params, method) => {
+        const query = { text, params };
+        if (method === 'run') {
+            await executor.execute(query);
+            return { rows: [] };
+        }
+        const result = await executor.execute(query, AS_ARRAYS);
+        // `get` asks for one row and is handed that row, not a list holding it.
+        return method === 'get' ? { rows: result.rows[0] ?? NO_ROW } : { rows: result.rows };
+    }, config);
+}
+/**
+ * Drizzle over a Postgres handle, or over the `tx` executor of one.
+ *
+ * Declare tables with `pgTable`.
+ */
+export function createPostgresDrizzle(executor, config) {
+    assertDialect(executor, 'postgres');
+    return drizzlePostgres(async (text, params, method) => {
+        const query = { text, params };
+        // `execute` is the raw path — `db.execute(sql\`…\`)` — and its caller reads
+        // rows by name. Only `all` feeds Drizzle's positional mapper.
+        if (method === 'execute')
+            return { rows: (await executor.execute(query)).rows };
+        return { rows: (await executor.execute(query, AS_ARRAYS)).rows };
+    }, config);
+}
+/**
+ * Drizzle over a MySQL or MariaDB handle, or over the `tx` executor of one.
+ *
+ * Declare tables with `mysqlTable`.
+ */
+export function createMysqlDrizzle(executor, config) {
+    assertDialect(executor, 'mysql');
+    return drizzleMysql(async (text, params, method) => {
+        const query = { text, params };
+        if (method === 'all') {
+            return { rows: (await executor.execute(query, AS_ARRAYS)).rows };
+        }
+        // A write reaches Drizzle as a result header, not as rows: that is where it
+        // reads the auto-increment key back for `$returningId()`. MySQL has no
+        // RETURNING, so this is the only way to learn it.
+        const result = await executor.execute(query);
+        if (returnsRows(text))
+            return { rows: result.rows };
+        return {
+            rows: [{ insertId: result.insertId ?? 0, affectedRows: result.rowsAffected }],
+            insertId: result.insertId ?? 0,
+            affectedRows: result.rowsAffected,
+        };
+    }, config);
+}
+//# sourceMappingURL=drizzle.js.map

package/dist/db/drizzle.js.map

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

package/dist/db/index.d.ts

@@ -0,0 +1,28 @@
+import { type DriverRegistry } from '../drivers/index.js';
+import type { Logger } from '../logger/index.js';
+import type { DatabaseConfig, DatabaseDriverOptions, DatabaseHandle } from './types.js';
+export type { CompiledQuery, SqlFragment } from './dialect.js';
+export { compile, encodeValue, identifier, isWrite, limit, returnsRows, sql, unsafeRaw, } from './dialect.js';
+export type { MySqlRemoteDatabase, PgRemoteDatabase, SqliteRemoteDatabase, } from './drizzle.js';
+export { createMysqlDrizzle, createPostgresDrizzle, createSqliteDrizzle, drizzleTransaction, } from './drizzle.js';
+export type { MysqlHandleOptions } from './mysql.js';
+export { createMysqlHandle, loadMysqlModule, mysqlDatabaseDriver } from './mysql.js';
+export type { PostgresHandleOptions } from './postgres.js';
+export { createPostgresHandle, loadPostgresModule, postgresDatabaseDriver } from './postgres.js';
+export type { SqliteHandleOptions } from './sqlite.js';
+export { createSqliteHandle, loadSqliteModule, sqliteDatabaseDriver } from './sqlite.js';
+export type { DatabaseConfig, DatabaseDialect, DatabaseDriverOptions, DatabaseHandle, ExecuteOptions, QueryResult, SqlExecutor, TransactionOptions, } from './types.js';
+export { DATABASE_DIALECTS } from './types.js';
+export interface DatabaseRegistryOptions extends DatabaseDriverOptions {
+    readonly logger?: Logger;
+}
+/**
+ * The database drivers Cogenta ships.
+ *
+ * SQLite is registered as `degraded` on purpose: it works everywhere and needs
+ * nothing, but it is one machine, has no vector index, and does not survive a
+ * fleet. Postgres and MySQL register as `optimal` when their optional client is
+ * installed.
+ */
+export declare function createDatabaseRegistry(options?: DatabaseRegistryOptions): DriverRegistry<DatabaseHandle, DatabaseConfig>;
+//# sourceMappingURL=index.d.ts.map

package/dist/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEvF,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC9D,OAAO,EACL,OAAO,EACP,WAAW,EACX,UAAU,EACV,OAAO,EACP,KAAK,EACL,WAAW,EACX,GAAG,EACH,SAAS,GACV,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACpF,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAChG,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACxF,YAAY,EACV,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,WAAW,EACX,WAAW,EACX,kBAAkB,GACnB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC,cAAc,CAAC,cAAc,EAAE,cAAc,CAAC,CAYhD"}

package/dist/db/index.js

@@ -0,0 +1,30 @@
+import { createDriverRegistry } from '../drivers/index.js';
+import { mysqlDatabaseDriver } from './mysql.js';
+import { postgresDatabaseDriver } from './postgres.js';
+import { sqliteDatabaseDriver } from './sqlite.js';
+export { compile, encodeValue, identifier, isWrite, limit, returnsRows, sql, unsafeRaw, } from './dialect.js';
+export { createMysqlDrizzle, createPostgresDrizzle, createSqliteDrizzle, drizzleTransaction, } from './drizzle.js';
+export { createMysqlHandle, loadMysqlModule, mysqlDatabaseDriver } from './mysql.js';
+export { createPostgresHandle, loadPostgresModule, postgresDatabaseDriver } from './postgres.js';
+export { createSqliteHandle, loadSqliteModule, sqliteDatabaseDriver } from './sqlite.js';
+export { DATABASE_DIALECTS } from './types.js';
+/**
+ * The database drivers Cogenta ships.
+ *
+ * SQLite is registered as `degraded` on purpose: it works everywhere and needs
+ * nothing, but it is one machine, has no vector index, and does not survive a
+ * fleet. Postgres and MySQL register as `optimal` when their optional client is
+ * installed.
+ */
+export function createDatabaseRegistry(options = {}) {
+    const { logger } = options;
+    const registry = createDriverRegistry({
+        need: 'database',
+        ...(logger === undefined ? {} : { logger }),
+    });
+    registry.register(postgresDatabaseDriver());
+    registry.register(mysqlDatabaseDriver());
+    registry.register(sqliteDatabaseDriver());
+    return registry;
+}
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAuB,MAAM,qBAAqB,CAAA;AAE/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAIlD,OAAO,EACL,OAAO,EACP,WAAW,EACX,UAAU,EACV,OAAO,EACP,KAAK,EACL,WAAW,EACX,GAAG,EACH,SAAS,GACV,MAAM,cAAc,CAAA;AAMrB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAEpF,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAEhG,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAWxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAM9C;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAO,GAA4B,EAAE;IAErC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IAC1B,MAAM,QAAQ,GAAG,oBAAoB,CAAiC;QACpE,IAAI,EAAE,UAAU;QAChB,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5C,CAAC,CAAA;IAEF,QAAQ,CAAC,QAAQ,CAAC,sBAAsB,EAAE,CAAC,CAAA;IAC3C,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,EAAE,CAAC,CAAA;IACxC,QAAQ,CAAC,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAA;IAEzC,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/dist/db/mysql.d.ts

@@ -0,0 +1,39 @@
+import type { Driver } from '../drivers/index.js';
+import type { DatabaseConfig, DatabaseHandle } from './types.js';
+/** Only the slice of `mysql2/promise` this driver uses. */
+interface ResultSetHeader {
+    readonly affectedRows: number;
+    readonly insertId: number;
+}
+type MysqlRows = Record<string, unknown>[] | unknown[][];
+type MysqlQueryResult = [MysqlRows | ResultSetHeader, unknown];
+/** The options form of a statement, the only one that can ask for value lists. */
+interface MysqlQueryOptions {
+    readonly sql: string;
+    readonly values?: readonly unknown[];
+    readonly rowsAsArray?: boolean;
+}
+interface MysqlQueries {
+    query(sql: string | MysqlQueryOptions, values?: readonly unknown[]): Promise<MysqlQueryResult>;
+    execute(sql: string | MysqlQueryOptions, values?: readonly unknown[]): Promise<MysqlQueryResult>;
+}
+interface MysqlConnection extends MysqlQueries {
+    release(): void;
+}
+interface MysqlPool extends MysqlQueries {
+    getConnection(): Promise<MysqlConnection>;
+    end(): Promise<void>;
+}
+interface MysqlModuleLike {
+    createPool: (options: Record<string, unknown>) => MysqlPool;
+}
+/** `mysql2` is an optional peer: a site on SQLite or Postgres never installs it. */
+export declare function loadMysqlModule(): Promise<MysqlModuleLike | null>;
+export interface MysqlHandleOptions {
+    readonly url: string;
+    readonly poolSize?: number;
+}
+export declare function createMysqlHandle(options: MysqlHandleOptions): Promise<DatabaseHandle>;
+export declare function mysqlDatabaseDriver(): Driver<DatabaseHandle, DatabaseConfig>;
+export {};
+//# sourceMappingURL=mysql.d.ts.map

package/dist/db/mysql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.d.ts","sourceRoot":"","sources":["../../src/db/mysql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,qBAAqB,CAAA;AAG/D,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EAKf,MAAM,YAAY,CAAA;AAEnB,2DAA2D;AAC3D,UAAU,eAAe;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,OAAO,EAAE,EAAE,CAAA;AAExD,KAAK,gBAAgB,GAAG,CAAC,SAAS,GAAG,eAAe,EAAE,OAAO,CAAC,CAAA;AAE9D,kFAAkF;AAClF,UAAU,iBAAiB;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED,UAAU,YAAY;IACpB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC9F,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;CACjG;AAED,UAAU,eAAgB,SAAQ,YAAY;IAC5C,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,UAAU,SAAU,SAAQ,YAAY;IACtC,aAAa,IAAI,OAAO,CAAC,eAAe,CAAC,CAAA;IACzC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACrB;AAED,UAAU,eAAe;IACvB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,SAAS,CAAA;CAC5D;AAED,oFAAoF;AACpF,wBAAsB,eAAe,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAMvE;AA0ED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAuF5F;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,cAAc,EAAE,cAAc,CAAC,CA+E5E"}