@lunora/hyperdrive 1.0.0-alpha.22 → 1.0.0-alpha.221

package/dist/packem_shared/types.d-DKB5Qb1Z.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Public types for `@lunora/hyperdrive`.
+ *
+ * Hyperdrive points at a database **Lunora does not own**. Everything here is
+ * deliberately structural (no hard dependency on `@cloudflare/workers-types` or
+ * any SQL driver) so unit tests can pass plain-object doubles, exactly like the
+ * `D1DatabaseLike` projection in `@lunora/d1`.
+ *
+ * The hard constraint, restated wherever this surface is used: Hyperdrive
+ * queries are **non-deterministic** (forbidden in `query`/`mutation`, allowed
+ * only in `action`s — see the `hyperdrive_outside_action` advisor lint), and
+ * external writes are **invisible to Lunora live queries** — a subscription will
+ * NOT re-run when an external Postgres/MySQL row changes.
+ */
+/**
+ * Structural projection of the Cloudflare `Hyperdrive` binding (`env.HYPERDRIVE`).
+ *
+ * Mirrors the fields of the real `Hyperdrive` from `@cloudflare/workers-types`
+ * but stays structural so a unit test can pass a plain object. At runtime only
+ * `connectionString` is needed to construct a driver; the discrete connection
+ * parts are surfaced for drivers that prefer a config object over a DSN.
+ */
+interface HyperdriveLike {
+  /** A connection string Hyperdrive routes through its pooled, cached edge connection. */
+  connectionString: string;
+  /** Database name component of the connection. */
+  database: string;
+  /** Host Hyperdrive presents to the driver (the local proxy, not your origin DB). */
+  host: string;
+  /** Password component of the connection. */
+  password: string;
+  /** Port Hyperdrive presents to the driver. */
+  port: number;
+  /** User component of the connection. */
+  user: string;
+}
+/**
+ * The connection config surfaced by {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive}: the raw
+ * `connectionString` plus the discrete parts, ready to hand to a driver.
+ */
+interface HyperdriveConnection {
+  /** Database name. */
+  database: string;
+  /** Host (Hyperdrive's local proxy). */
+  host: string;
+  /** Password. */
+  password: string;
+  /** Port. */
+  port: number;
+  /** User. */
+  user: string;
+}
+/**
+ * The driver-agnostic SQL surface bound to `ctx.sql` on **`ActionCtx` only**.
+ *
+ * This is the exact type the generated ctx imports as
+ * `import("@lunora/hyperdrive").SqlClient`. Keep the name and shape stable — the
+ * codegen ctx wiring (Phase 1) depends on it.
+ *
+ * It is intentionally minimal — a single parameterised `query` — so it maps onto
+ * `postgres` (postgres.js), `pg` (node-postgres) and `mysql2` alike via the
+ * {@link import("./create-hyperdrive").fromPostgresJs | fromPostgresJs} /
+ * {@link import("./create-hyperdrive").fromNodePg | fromNodePg} /
+ * {@link import("./create-hyperdrive").fromMysql2 | fromMysql2} adapters. Use
+ * positional placeholders that match your driver (`$1, $2` for Postgres, `?` for
+ * MySQL); the package does not rewrite SQL.
+ *
+ * Reminder (also on the emitted JSDoc): non-deterministic, action-only,
+ * non-reactive — writes here are not tracked by Lunora live queries.
+ */
+interface SqlClient {
+  /**
+   * The database system behind this client, as OTel names it in
+   * `db.system.name`. Stamped by the driver adapters ({@link import("./create-hyperdrive").fromPostgresJs | fromPostgresJs}
+   * / {@link import("./create-hyperdrive").fromNodePg | fromNodePg} → `"postgresql"`,
+   * {@link import("./create-hyperdrive").fromMysql2 | fromMysql2} → `"mysql"`) so `ctx.sql`'s automatic
+   * instrumentation reports the real system. Optional: a hand-built client may
+   * omit it and is then reported as `"other_sql"`.
+   */
+  readonly dbSystem?: "mysql" | "postgresql";
+  /**
+   * Run a parameterised SQL statement and return the result rows.
+   *
+   * SECURITY: `text` is executed verbatim — the package never rewrites or
+   * escapes it. NEVER interpolate untrusted/user input into `text`; put every
+   * value in `params` and reference it with a positional placeholder (`$1`/`?`).
+   * Building `text` by string-concatenating request data is a SQL-injection
+   * sink against your own Postgres/MySQL. Identifiers (table/column names) can't
+   * be parameterised — allowlist them against a fixed set, don't interpolate.
+   * @param text SQL text with driver-native positional placeholders.
+   * @param params Bound parameter values, positionally matched to `text`.
+   * @returns The rows the statement produced (empty for non-`SELECT`s that
+   * return no rows).
+   */
+  query: <Row = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>) => Promise<Row[]>;
+  /**
+   * Run `work` against a client pinned to one connection inside one
+   * transaction: committed when `work` resolves, rolled back when it throws.
+   * {@link import("./create-hyperdrive").fromPostgresJs | fromPostgresJs} provides it over postgres.js's `begin`;
+   * `@lunora/hyperdrive/global`'s `buildPgExec` uses it so a `.global()` row
+   * write and its aggregate/rank/CDC companions commit together. Absent, they
+   * commit one statement at a time.
+   */
+  transaction?: <T>(work: (tx: SqlClient) => Promise<T>) => Promise<T>;
+}
+/**
+ * Structural projection of a `pg` (node-postgres) `Client`/`Pool`. Only the
+ * `query` method `fromNodePg` calls is required, kept structural for testing.
+ *
+ * Method syntax, not an arrow property — see {@link PostgresJsLike}.
+ */
+interface NodePgLike {
+  query(this: void, text: string, params?: ReadonlyArray<unknown>): Promise<{
+    rows: unknown[];
+  }>;
+}
+/**
+ * Structural projection of a `postgres` (postgres.js) tagged-template client.
+ * The adapter uses the `.unsafe(text, params)` escape hatch so callers keep
+ * full control of the parameter list.
+ *
+ * **`unsafe` is declared with METHOD syntax, and that is load-bearing.** Under
+ * `strictFunctionTypes` an arrow PROPERTY is checked contravariantly in its
+ * parameters, so a driver whose `unsafe` takes a MUTABLE array — which real
+ * postgres.js does (`parameters?: ParameterOrJSON<never>[]`) — is not assignable
+ * to one declared `params?: ReadonlyArray<unknown>`. As an arrow property this
+ * projection could therefore never accept the package it projects: every
+ * consumer got
+ * `TS2345: Argument of type 'Sql<{}>' is not assignable to parameter of type
+ * 'PostgresJsLike'`, and this repo's own test reached for
+ * `as unknown as PostgresJsLike` to get past it. Method syntax is checked
+ * bivariantly, which is what a structural projection of someone else's type
+ * needs — `readonly unknown[]` and postgres.js's mutable array relate in one
+ * direction, which is all bivariance asks for.
+ */
+interface PostgresJsLike {
+  /** postgres.js's `sql.begin(fn)`: reserves one connection and runs `fn` inside `BEGIN` … `COMMIT`. */
+  begin?(this: void, work: (tx: PostgresJsLike) => Promise<unknown>): Promise<unknown>;
+  unsafe(this: void, text: string, params?: ReadonlyArray<unknown>, options?: {
+    prepare?: boolean;
+  }): Promise<unknown>;
+}
+/**
+ * Structural projection of a `mysql2/promise` connection/pool. `mysql2`'s
+ * `query` resolves to a `[rows, fields]` tuple; the adapter takes the first
+ * element as the rows.
+ *
+ * `query`, not `execute`: `execute` is a protocol-level prepared statement
+ * (`COM_STMT_PREPARE` + the binary protocol), which Hyperdrive does not support
+ * for MySQL. `query` interpolates the `?` placeholders client-side and sends
+ * plain text. Strings are quoted with `''` for a quote and `\\` for a
+ * backslash, so a server whose `sql_mode` includes `NO_BACKSLASH_ESCAPES` is
+ * unsupported: there a backslash is stored twice. No value can end its literal
+ * under either mode. mysql2 skips a `?` inside a quoted string or comment, but
+ * reads `??` as an identifier placeholder.
+ *
+ * Method syntax, not an arrow property — see {@link PostgresJsLike} — but here
+ * that is necessary and NOT sufficient, which is why `params` is `unknown`.
+ *
+ * mysql2 types its second argument as a single `QueryValues`: a union of
+ * scalars, `QueryValues[]` and `{ [key: string]: QueryValues }`. Declared
+ * `params?: ReadonlyArray<unknown>` this projection could never accept the
+ * driver it projects — bivariance needs the two parameter types to relate in
+ * ONE direction and they relate in neither (`readonly unknown[] | undefined` is
+ * not a `QueryValues`, and a `string` is not an array).
+ *
+ * `unknown` is the narrowest supertype of `QueryValues` that does not restate
+ * mysql2's union here. Restating it would be the vacuous shim all over again —
+ * a local copy that drifts from the package it mirrors and makes the gate pass
+ * while a consumer fails.
+ *
+ * The looseness is confined to the INPUT position: this types the driver a
+ * caller hands to `fromMysql2`, not what anyone passes to
+ * {@link SqlClient.query}, which still declares `ReadonlyArray<unknown>`. Every
+ * call site in this package forwards an array, and the driver validates the
+ * values at runtime regardless.
+ */
+interface Mysql2Like {
+  query(this: void, text: string, params?: unknown): Promise<[unknown, unknown]>;
+}
+export { HyperdriveLike as H, Mysql2Like as M, NodePgLike as N, PostgresJsLike as P, SqlClient as S, HyperdriveConnection as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/hyperdrive",
-  "version": "1.0.0-alpha.22",
+  "version": "1.0.0-alpha.221",
   "description": "Bring-your-own Postgres/MySQL for Lunora via Cloudflare Hyperdrive: a driver-agnostic, action-only ctx.sql",
   "keywords": [
     "cloudflare",
@@ -50,9 +50,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/do": "1.0.0-alpha.22",
-    "@lunora/sql-store": "1.0.0-alpha.22",
-    "drizzle-orm": "^0.45.2"
+    "@lunora/errors": ">=1.0.0-alpha.51 <2.0.0-0",
+    "@lunora/platform": "1.0.0-alpha.77",
+    "@lunora/shard-engine": "1.0.0-alpha.178",
+    "@lunora/sql-store": "1.0.0-alpha.226",
+    "drizzle-orm": "1.0.0-rc.5"
   },
   "peerDependencies": {
     "mysql2": "*",

package/dist/packem_shared/buildMysqlExec-DBbCjyq3.mjs

@@ -1,23 +0,0 @@
-const buildPgExec = (client) => {
-  return {
-    all: (sql, params) => client.query(sql, params),
-    run: async (sql, params) => {
-      await client.query(sql, params);
-      return { rowsAffected: 0 };
-    }
-  };
-};
-const buildMysqlExec = (connection) => {
-  return {
-    all: async (sql, params) => {
-      const [rows] = await connection.execute(sql, params);
-      return rows;
-    },
-    run: async (sql, params) => {
-      const [result] = await connection.execute(sql, params);
-      return { rowsAffected: result.affectedRows ?? 0 };
-    }
-  };
-};
-
-export { buildMysqlExec, buildPgExec };

package/dist/packem_shared/createHyperdrive-DD8GoDZo.mjs

@@ -1,36 +0,0 @@
-const createHyperdrive = (binding) => {
-  const config = {
-    database: binding.database,
-    host: binding.host,
-    password: binding.password,
-    port: binding.port,
-    user: binding.user
-  };
-  return { config, connectionString: binding.connectionString };
-};
-const fromPostgresJs = (client) => {
-  return {
-    query: async (text, params = []) => {
-      const rows = await client.unsafe(text, params);
-      return rows;
-    }
-  };
-};
-const fromNodePg = (client) => {
-  return {
-    query: async (text, params = []) => {
-      const result = await client.query(text, params);
-      return result.rows;
-    }
-  };
-};
-const fromMysql2 = (connection) => {
-  return {
-    query: async (text, params = []) => {
-      const [rows] = await connection.execute(text, params);
-      return Array.isArray(rows) ? rows : [];
-    }
-  };
-};
-
-export { createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs };

package/dist/packem_shared/mysqlDialect-oNhZ58s8.mjs

@@ -1,102 +0,0 @@
-import { sqliteEncode, sqliteDecode } from '@lunora/sql-store';
-import { sql } from 'drizzle-orm';
-
-const PG_UNIQUE_VIOLATION_RE = /duplicate key value violates unique constraint/iu;
-const mysqlColumnType = (kind) => {
-  switch (kind) {
-    case "array":
-    case "object":
-    case "record": {
-      return "JSON";
-    }
-    case "bigint": {
-      return "VARCHAR(64)";
-    }
-    case "boolean": {
-      return "TINYINT";
-    }
-    case "bytes": {
-      return "LONGBLOB";
-    }
-    case "date":
-    case "number":
-    case "timestamp": {
-      return "DOUBLE";
-    }
-    default: {
-      return "LONGTEXT";
-    }
-  }
-};
-const MYSQL_PREFIX_INDEX_RE = /TEXT|BLOB/u;
-const postgresDialect = {
-  companionTypes: {
-    autoincrementPrimaryKey: "BIGSERIAL PRIMARY KEY",
-    integer: "INTEGER",
-    key: "TEXT",
-    real: "DOUBLE PRECISION",
-    text: "TEXT"
-  },
-  columnType: (kind) => {
-    switch (kind) {
-      case "boolean": {
-        return "INTEGER";
-      }
-      case "bytes": {
-        return "BYTEA";
-      }
-      case "date":
-      case "number":
-      case "timestamp": {
-        return "DOUBLE PRECISION";
-      }
-      default: {
-        return "TEXT";
-      }
-    }
-  },
-  decode: (value, kind) => sqliteDecode(value, kind),
-  encode: (value) => sqliteEncode(value),
-  frameworkColumns: () => [
-    { name: "id", type: "TEXT PRIMARY KEY" },
-    { name: "_creationTime", type: "DOUBLE PRECISION NOT NULL" }
-  ],
-  isUniqueViolation: (error) => {
-    const { code } = error;
-    return code === "23505" || error instanceof Error && PG_UNIQUE_VIOLATION_RE.test(error.message);
-  },
-  name: "postgres",
-  supportsReturning: true,
-  tableExists: (table) => sql`SELECT table_name FROM information_schema.tables WHERE table_name = ${table}`
-};
-const mysqlDialect = {
-  affectedRows: (result) => result.rowsAffected,
-  companionTypes: {
-    autoincrementPrimaryKey: "BIGINT AUTO_INCREMENT PRIMARY KEY",
-    integer: "INTEGER",
-    // VARCHAR so it can be a PRIMARY KEY and be fully indexed (TEXT cannot,
-    // without a prefix length). 768 = InnoDB utf8mb4 single-column index limit.
-    key: "VARCHAR(768)",
-    real: "DOUBLE",
-    // Unbounded post-image storage (CDC `doc`); never an index key, so no bound.
-    text: "LONGTEXT"
-  },
-  columnType: (kind) => mysqlColumnType(kind),
-  decode: (value, kind) => sqliteDecode(value, kind),
-  encode: (value) => sqliteEncode(value),
-  frameworkColumns: () => [
-    { name: "id", type: "VARCHAR(768) PRIMARY KEY" },
-    { name: "_creationTime", type: "DOUBLE NOT NULL" }
-  ],
-  // InnoDB can't index a TEXT/LONGTEXT/BLOB column without a key prefix; bound it to 768 chars.
-  indexKeyPrefix: (kind) => MYSQL_PREFIX_INDEX_RE.test(mysqlColumnType(kind)) ? 768 : void 0,
-  isUniqueViolation: (error) => {
-    const candidate = error;
-    return candidate.errno === 1062 || candidate.code === "ER_DUP_ENTRY";
-  },
-  name: "mysql",
-  supportsReturning: false,
-  tableExists: (table) => sql`SELECT table_name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ${table}`
-};
-
-export { mysqlDialect, postgresDialect };

package/dist/packem_shared/projectSourceRow-DtKuMRIm.mjs

@@ -1,10 +0,0 @@
-import { liftSourceId } from '@lunora/do';
-
-const projectSourceRow = (row, options = {}) => liftSourceId(row, options);
-const pullSourceRows = async (sql, options) => {
-  const { idColumn, map, params, query } = options;
-  const rows = await sql.query(query, params);
-  return rows.map((row) => projectSourceRow(row, { idColumn, map }));
-};
-
-export { projectSourceRow, pullSourceRows };