@lunora/hyperdrive 1.0.0-alpha.211 → 1.0.0-alpha.212

package/dist/global.d.mts

@@ -22,8 +22,8 @@
  * `createPool({ flags: ["FOUND_ROWS"] })`) so the affected-rows OCC guard sees
  * matched (not changed) rows — see {@link buildMysqlExec}.
  */
-import { DatabaseWriterLike } from '@lunora/shard-engine';
-import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
+import { SchemaLike, ImportConflictMode, CdcChange, DatabaseWriterLike } from '@lunora/shard-engine';
+import { SqlExec, SqlDialect, SqlCtxDbOptions, FacetGlobalColumnOptions, GlobalFacetResult, GlobalTableInfo, ReadGlobalTablePageOptions, GlobalTablePage, ExportRow, ImportResult } from '@lunora/sql-store';
 import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-B2JdXSms.mjs";
 import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
 /**
@@ -171,8 +171,77 @@ interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dial
  * D1 store options.
  */
 declare const createHyperdriveGlobalCtxDb: ({ engine, exec, ...rest }: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
+/** Options for {@link exportHyperdriveGlobalRows}. */
+interface ExportHyperdriveGlobalRowsOptions {
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+  /** Table allowlist; empty or absent exports every `.global()` table. */
+  tables?: ReadonlyArray<string>;
+}
+/**
+ * The admin export's global plane on Hyperdrive: yield every requested
+ * `.global()` table's rows, keyset-paged. Provisions the schema's tables first,
+ * so a table that was never written exports as empty instead of failing.
+ */
+declare const exportHyperdriveGlobalRows: ({ engine, exec, schema, tables }: ExportHyperdriveGlobalRowsOptions) => AsyncGenerator<ExportRow, void, undefined>;
+/** Options for {@link importHyperdriveGlobalRows}. */
+interface ImportHyperdriveGlobalRowsOptions {
+  /** Append each insert to the global CDC log, like any other write — the app's own `cdc` setting. */
+  cdc: boolean;
+  /** Validate and report shape errors only; nothing is probed or written. */
+  dryRun?: boolean;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  /** `"replace"` overwrites a row whose `_id` already exists; `"skip"` (the default) counts it as a conflict. */
+  onConflict?: ImportConflictMode;
+  rows: ReadonlyArray<ExportRow>;
+  schema: SchemaLike;
+  startLine?: number;
+}
+/**
+ * The admin import's global plane on Hyperdrive: insert snapshot rows through
+ * the same store core `.global()` writes use. A row whose `_id` already exists
+ * is a conflict left unchanged, unless `onConflict` is `"replace"`.
+ */
+declare const importHyperdriveGlobalRows: ({ cdc, dryRun, engine, exec, onConflict, rows, schema, startLine }: ImportHyperdriveGlobalRowsOptions) => Promise<ImportResult>;
 /** Convenience: a **Postgres** `.global()` writer from a row-client (postgres.js/pg over Hyperdrive). */
 declare const createPostgresGlobalCtxDb: (client: RowClient, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
 /** Convenience: a **MySQL** `.global()` writer from a `mysql2/promise` connection/pool (created with `flags: ["FOUND_ROWS"]`). */
 declare const createMysqlGlobalCtxDb: (connection: Mysql2Execute, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
-export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type PgVectorIndexOptions, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+/** The studio's global data browser over a Hyperdrive database — every table in the connection's schema, internal ones hidden. */
+interface HyperdriveGlobalIntrospector {
+  facetColumn: (options: FacetGlobalColumnOptions) => Promise<GlobalFacetResult>;
+  listTables: () => Promise<GlobalTableInfo[]>;
+  readTablePage: (options: ReadGlobalTablePageOptions) => Promise<GlobalTablePage>;
+}
+/** Build the studio's global-browser introspector for a Hyperdrive `.global()` store. */
+declare const createHyperdriveGlobalIntrospector: (engine: HyperdriveEngine, exec: SqlExec, schema: SchemaLike) => HyperdriveGlobalIntrospector;
+/**
+ * The admin CDC sync's global plane on Hyperdrive: a page of the global
+ * `__cdc_log` past `sinceSeq`. The log only exists once a CDC-enabled writer has
+ * run, so its absence is "nothing has changed yet" — an empty page that leaves
+ * the cursor where it was — not an error.
+ */
+declare const readHyperdriveGlobalCdc: (engine: HyperdriveEngine, exec: SqlExec, request: {
+  limit?: number;
+  now?: number;
+  sinceSeq: number;
+}) => Promise<{
+  changes: CdcChange[];
+  cursor: number;
+}>;
+/**
+ * The admin point-in-time apply's global plane on Hyperdrive: replay CDC changes
+ * in order through the store core (insert, falling back to replace). The writer
+ * carries the app's `cdc` setting so the replay appends to the global changelog
+ * like any other write. Returns the number replayed.
+ */
+declare const applyHyperdriveGlobalCdc: (options: {
+  cdc: boolean;
+  changes: ReadonlyArray<CdcChange>;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+}) => Promise<number>;
+export { CreateHyperdriveGlobalCtxDbOptions, ExportHyperdriveGlobalRowsOptions, HyperdriveEngine, HyperdriveGlobalIntrospector, ImportHyperdriveGlobalRowsOptions, type Mysql2Execute, type PgVectorIndexOptions, type RowClient, applyHyperdriveGlobalCdc, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createHyperdriveGlobalIntrospector, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, exportHyperdriveGlobalRows, importHyperdriveGlobalRows, mysqlDialect, postgresDialect, readHyperdriveGlobalCdc };

package/dist/global.d.ts

@@ -22,8 +22,8 @@
  * `createPool({ flags: ["FOUND_ROWS"] })`) so the affected-rows OCC guard sees
  * matched (not changed) rows — see {@link buildMysqlExec}.
  */
-import { DatabaseWriterLike } from '@lunora/shard-engine';
-import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
+import { SchemaLike, ImportConflictMode, CdcChange, DatabaseWriterLike } from '@lunora/shard-engine';
+import { SqlExec, SqlDialect, SqlCtxDbOptions, FacetGlobalColumnOptions, GlobalFacetResult, GlobalTableInfo, ReadGlobalTablePageOptions, GlobalTablePage, ExportRow, ImportResult } from '@lunora/sql-store';
 import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-B2JdXSms.js";
 import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
 /**
@@ -171,8 +171,77 @@ interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dial
  * D1 store options.
  */
 declare const createHyperdriveGlobalCtxDb: ({ engine, exec, ...rest }: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
+/** Options for {@link exportHyperdriveGlobalRows}. */
+interface ExportHyperdriveGlobalRowsOptions {
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+  /** Table allowlist; empty or absent exports every `.global()` table. */
+  tables?: ReadonlyArray<string>;
+}
+/**
+ * The admin export's global plane on Hyperdrive: yield every requested
+ * `.global()` table's rows, keyset-paged. Provisions the schema's tables first,
+ * so a table that was never written exports as empty instead of failing.
+ */
+declare const exportHyperdriveGlobalRows: ({ engine, exec, schema, tables }: ExportHyperdriveGlobalRowsOptions) => AsyncGenerator<ExportRow, void, undefined>;
+/** Options for {@link importHyperdriveGlobalRows}. */
+interface ImportHyperdriveGlobalRowsOptions {
+  /** Append each insert to the global CDC log, like any other write — the app's own `cdc` setting. */
+  cdc: boolean;
+  /** Validate and report shape errors only; nothing is probed or written. */
+  dryRun?: boolean;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  /** `"replace"` overwrites a row whose `_id` already exists; `"skip"` (the default) counts it as a conflict. */
+  onConflict?: ImportConflictMode;
+  rows: ReadonlyArray<ExportRow>;
+  schema: SchemaLike;
+  startLine?: number;
+}
+/**
+ * The admin import's global plane on Hyperdrive: insert snapshot rows through
+ * the same store core `.global()` writes use. A row whose `_id` already exists
+ * is a conflict left unchanged, unless `onConflict` is `"replace"`.
+ */
+declare const importHyperdriveGlobalRows: ({ cdc, dryRun, engine, exec, onConflict, rows, schema, startLine }: ImportHyperdriveGlobalRowsOptions) => Promise<ImportResult>;
 /** Convenience: a **Postgres** `.global()` writer from a row-client (postgres.js/pg over Hyperdrive). */
 declare const createPostgresGlobalCtxDb: (client: RowClient, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
 /** Convenience: a **MySQL** `.global()` writer from a `mysql2/promise` connection/pool (created with `flags: ["FOUND_ROWS"]`). */
 declare const createMysqlGlobalCtxDb: (connection: Mysql2Execute, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
-export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type PgVectorIndexOptions, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+/** The studio's global data browser over a Hyperdrive database — every table in the connection's schema, internal ones hidden. */
+interface HyperdriveGlobalIntrospector {
+  facetColumn: (options: FacetGlobalColumnOptions) => Promise<GlobalFacetResult>;
+  listTables: () => Promise<GlobalTableInfo[]>;
+  readTablePage: (options: ReadGlobalTablePageOptions) => Promise<GlobalTablePage>;
+}
+/** Build the studio's global-browser introspector for a Hyperdrive `.global()` store. */
+declare const createHyperdriveGlobalIntrospector: (engine: HyperdriveEngine, exec: SqlExec, schema: SchemaLike) => HyperdriveGlobalIntrospector;
+/**
+ * The admin CDC sync's global plane on Hyperdrive: a page of the global
+ * `__cdc_log` past `sinceSeq`. The log only exists once a CDC-enabled writer has
+ * run, so its absence is "nothing has changed yet" — an empty page that leaves
+ * the cursor where it was — not an error.
+ */
+declare const readHyperdriveGlobalCdc: (engine: HyperdriveEngine, exec: SqlExec, request: {
+  limit?: number;
+  now?: number;
+  sinceSeq: number;
+}) => Promise<{
+  changes: CdcChange[];
+  cursor: number;
+}>;
+/**
+ * The admin point-in-time apply's global plane on Hyperdrive: replay CDC changes
+ * in order through the store core (insert, falling back to replace). The writer
+ * carries the app's `cdc` setting so the replay appends to the global changelog
+ * like any other write. Returns the number replayed.
+ */
+declare const applyHyperdriveGlobalCdc: (options: {
+  cdc: boolean;
+  changes: ReadonlyArray<CdcChange>;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+}) => Promise<number>;
+export { CreateHyperdriveGlobalCtxDbOptions, ExportHyperdriveGlobalRowsOptions, HyperdriveEngine, HyperdriveGlobalIntrospector, ImportHyperdriveGlobalRowsOptions, type Mysql2Execute, type PgVectorIndexOptions, type RowClient, applyHyperdriveGlobalCdc, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createHyperdriveGlobalIntrospector, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, exportHyperdriveGlobalRows, importHyperdriveGlobalRows, mysqlDialect, postgresDialect, readHyperdriveGlobalCdc };

package/dist/global.mjs

@@ -1 +1 @@
-import{createSqlCtxDb as c}from"@lunora/sql-store";import{postgresDialect as l,mysqlDialect as s}from"./packem_shared/mysqlDialect-BS1Sz60B.mjs";import{buildMysqlExec as a,buildPgExec as i}from"./packem_shared/buildMysqlExec-CjkrA5JG.mjs";import{createPgVectorIndex as d}from"./packem_shared/createPgVectorIndex-CSNnG065.mjs";const r=({engine:e,exec:t,...o})=>c({...o,dialect:e==="postgres"?l:s,exec:t}),p=(e,t)=>r({...t,engine:"postgres",exec:i(e)}),g=(e,t)=>r({...t,engine:"mysql",exec:a(e)});export{a as buildMysqlExec,i as buildPgExec,r as createHyperdriveGlobalCtxDb,g as createMysqlGlobalCtxDb,d as createPgVectorIndex,p as createPostgresGlobalCtxDb,s as mysqlDialect,l as postgresDialect};
+import{applyCdcChanges as d,CDC_LOG_TABLE as b}from"@lunora/shard-engine";import{createSqlCtxDb as p,readSqlGlobalTablePage as g,listSqlGlobalTables as m,facetSqlGlobalColumn as y,exportSqlGlobalRows as C,importSqlGlobalRows as G,readSqlCdcChanges as x}from"@lunora/sql-store";import{postgresDialect as q,mysqlDialect as u}from"./packem_shared/mysqlDialect-BS1Sz60B.mjs";import{buildMysqlExec as f,buildPgExec as v}from"./packem_shared/buildMysqlExec-CjkrA5JG.mjs";import{createPgVectorIndex as A}from"./packem_shared/createPgVectorIndex-CSNnG065.mjs";const o=e=>e==="postgres"?q:u,c=({engine:e,exec:l,...r})=>p({...r,dialect:o(e),exec:l}),H=({engine:e,exec:l,schema:r,tables:t})=>C(l,r,o(e),t===void 0?{}:{tables:t}),P=({cdc:e,dryRun:l,engine:r,exec:t,onConflict:a,rows:s,schema:n,startLine:i})=>G(c({cdc:e,engine:r,exec:t,schema:n}),n,o(r),{dryRun:l===!0,exec:t,onConflict:a??"skip",rows:s,...i===void 0?{}:{startLine:i}}),R=(e,l)=>c({...l,engine:"postgres",exec:v(e)}),T=(e,l)=>c({...l,engine:"mysql",exec:f(e)}),E=(e,l,r)=>{const t=o(e);return{facetColumn:a=>y(l,r,t,a),listTables:()=>m(l,r,t),readTablePage:a=>g(l,r,t,a)}},I=async(e,l,r)=>{const t=o(e),{params:a,sql:s}=t.render(t.tableExists(b));return(await l.all(s,a)).length===0?{changes:[],cursor:r.sinceSeq}:x(l,r,t)},M=async e=>(await d(c({cdc:e.cdc,engine:e.engine,exec:e.exec,schema:e.schema}),e.changes),e.changes.length);export{M as applyHyperdriveGlobalCdc,f as buildMysqlExec,v as buildPgExec,c as createHyperdriveGlobalCtxDb,E as createHyperdriveGlobalIntrospector,T as createMysqlGlobalCtxDb,A as createPgVectorIndex,R as createPostgresGlobalCtxDb,H as exportHyperdriveGlobalRows,P as importHyperdriveGlobalRows,u as mysqlDialect,q as postgresDialect,I as readHyperdriveGlobalCdc};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/hyperdrive",
-  "version": "1.0.0-alpha.211",
+  "version": "1.0.0-alpha.212",
   "description": "Bring-your-own Postgres/MySQL for Lunora via Cloudflare Hyperdrive: a driver-agnostic, action-only ctx.sql",
   "keywords": [
     "cloudflare",
@@ -52,8 +52,8 @@
   "dependencies": {
     "@lunora/errors": ">=1.0.0-alpha.51 <2.0.0-0",
     "@lunora/platform": "1.0.0-alpha.75",
-    "@lunora/shard-engine": "1.0.0-alpha.165",
-    "@lunora/sql-store": "1.0.0-alpha.214",
+    "@lunora/shard-engine": "1.0.0-alpha.167",
+    "@lunora/sql-store": "1.0.0-alpha.215",
     "drizzle-orm": "1.0.0-rc.5"
   },
   "peerDependencies": {