@proteinjs/db 1.58.0 → 1.58.1

package/index.ts

@@ -17,9 +17,11 @@ export * from './src/RecordIterator';
 export * from './src/CursorWindowPager';
 export * from './src/source/SourceRecord';
 export * from './src/source/SourceRecordRepo';
-// The sync runner behind Db.init's source-record leg. Public so consumer test harnesses can run
-// one boot of the sync directly (the exports map blocks deep dist imports).
-export { SourceRecordSyncRunner } from './src/source/SourceRecordSyncRunner';
+// The source-record sync's seam: its summary types and `getSourceRecordSync`. The runner itself is
+// server-only code (it reads package.json files off the booting process) behind the
+// `@proteinjs/db/source` subpath, which a server's boot imports once; a consumer test harness that
+// runs one boot of the sync directly imports it from there too.
+export * from './src/source/SourceRecordSync';
 export * from './src/MigrationRunner';
 export * from './src/QueryBuilderFactory';
 export * from './src/TableWatcher';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.58.0",
+  "version": "1.58.1",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -11,12 +11,19 @@
     "./test": {
       "types": "./dist/generated/test/index.d.ts",
       "default": "./dist/generated/test/index.js"
+    },
+    "./source": {
+      "types": "./dist/generated/source/index.d.ts",
+      "default": "./dist/generated/source/index.js"
     }
   },
   "typesVersions": {
     "*": {
       "test": [
         "dist/generated/test/index.d.ts"
+      ],
+      "source": [
+        "dist/generated/source/index.d.ts"
       ]
     }
   },
@@ -36,7 +43,7 @@
   "license": "MIT",
   "scripts": {
     "clean": "rm -rf dist/ node_modules/ generated/",
-    "build": "reflection-build && REFLECTION_SOURCE_DIRS=test,src REFLECTION_EXPORT_FROM=test/index.ts reflection-build && tsc",
+    "build": "reflection-build && REFLECTION_SOURCE_DIRS=test,src REFLECTION_EXPORT_FROM=test/index.ts reflection-build && REFLECTION_SOURCE_DIRS=source,src REFLECTION_EXPORT_FROM=source/index.ts reflection-build && tsc",
     "watch": "reflection-watch",
     "test": "jest --passWithNoTests"
   },
@@ -64,7 +71,8 @@
     "eslint-plugin-prettier": "5.1.3",
     "jest": "29.7.0",
     "ts-jest": "29.1.1",
-    "typescript": "5.2.2"
+    "typescript": "5.2.2",
+    "webpack": "5.88.2"
   },
-  "gitHead": "d11e74da6edf607eddb0844f00b61f912a22dcef"
+  "gitHead": "0c9fe556af1052933bb3e6fef08f9e33c129c2a6"
 }

package/{src/source → source}/SourceRecordSyncRunner.ts

@@ -1,10 +1,13 @@
+import * as fs from 'fs';
+import * as path from 'path';
 import { Logger } from '@proteinjs/logger';
 import { QueryBuilder } from '@proteinjs/db-query';
-import { getSourceRecordLoaders, SourceRecord, getSourceRecordTables } from './SourceRecord';
-import { Table } from '../Table';
-import { Db, getDbAsSystem } from '../Db';
-import { SourceRecordRepo } from './SourceRecordRepo';
-import { RecordSerializer } from '../Record';
+import { getSourceRecordLoaders, SourceRecord, getSourceRecordTables } from '../src/source/SourceRecord';
+import { Table } from '../src/Table';
+import { Db, getDbAsSystem } from '../src/Db';
+import { SourceRecordRepo } from '../src/source/SourceRecordRepo';
+import { RecordSerializer } from '../src/Record';
+import { SourceRecordLoadSummary, SourceRecordSync } from '../src/source/SourceRecordSync';
 
 type DeclaredRecord = {
   /** The owning package (the declaring loader's package) — the grain the sync prunes within. */
@@ -19,29 +22,12 @@ type SourceRecordsMap = {
   [tableName: string]: { table: Table<any>; records: DeclaredRecord[] };
 };
 
-/** What one boot of the sync did to one source-record table. */
-export type SourceRecordTableLoadSummary = {
-  inserts: number;
-  updates: number;
-  unchanged: number;
-  adopted: number;
-  /**
-   * Declarations whose natural key is held by a row the sync does not own (written at runtime —
-   * a person's own row, say): refused for this boot, that row left exactly as it is (see
-   * {@link SourceRecordOptions.naturalKey}).
-   */
-  refused: number;
-  deletes: number;
-  removedUpdates: number;
-  /** Rows stamped by a newer version of their declaring package — left exactly as they are. */
-  skippedNewer: number;
-  /** Source-loaded rows with no owner stamp that no declaration in this build claims. */
-  unowned: number;
-};
-
-export type SourceRecordLoadSummary = { [tableName: string]: SourceRecordTableLoadSummary };
-
-export class SourceRecordSyncRunner {
+/**
+ * The one {@link SourceRecordSync}: server-only code (it reads package.json files off the booting
+ * process) behind the `@proteinjs/db/source` subpath — a server's boot imports that subpath once,
+ * and reflection hands this runner to `Db.init` through `getSourceRecordSync`.
+ */
+export class SourceRecordSyncRunner implements SourceRecordSync {
   private logger = new Logger({ name: this.constructor.name });
 
   /** Memo of resolved package versions — one resolution (and at most one warning) per source. */
@@ -627,44 +613,39 @@ export class SourceRecordSyncRunner {
    *    `<pkg>/package.json` is usually not requireable), then the nearest package.json whose
    *    `name` matches is read walking up from it.
    *
-   * Returns undefined where neither road resolves — no Node `require` (browser bundles), or a
-   * package not resolvable from cwd. The sync then has no place in the version order for that
-   * package: it never touches its version-stamped rows, and what it writes is unversioned
-   * (see {@link isNewerStamp}). Logged once per boot so a misconfigured cwd is visible.
+   * Returns undefined where neither road resolves — a package not resolvable from cwd. The sync
+   * then has no place in the version order for that package: it never touches its
+   * version-stamped rows, and what it writes is unversioned (see {@link isNewerStamp}). Logged
+   * once per boot so a misconfigured cwd is visible.
+   *
+   * Plain Node here — `fs`, `path` and the CJS `require.resolve` — because this module is
+   * server-only code behind the `@proteinjs/db/source` subpath: the package's browser index never
+   * imports it (test/BrowserIndexNoNodeBuiltins.test.ts holds that line), so nothing here hides
+   * from a bundler.
    */
   private resolveSourceVersion(source: string): string | undefined {
-    // The ambient CJS `require` — the only require carrying `.resolve` (module.require does
-    // not). Every use below goes through the variable, so bundlers never see a statically
-    // analyzable `require(...)` call; in a browser bundle the runtime attempts throw into
-    // their catches and the method degrades to undefined.
-    const nodeRequire: NodeRequire | undefined =
-      typeof require === 'function' && typeof require.resolve === 'function' ? require : undefined;
-    const cwd = typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : undefined;
-    if (nodeRequire && cwd) {
-      try {
-        const path = nodeRequire('path');
-        const fs = nodeRequire('fs');
-        const ownVersion = this.packageVersionAt(fs, path.join(cwd, 'package.json'), source);
-        if (ownVersion) {
-          return ownVersion;
-        }
+    const cwd = process.cwd();
+    try {
+      const ownVersion = this.packageVersionAt(path.join(cwd, 'package.json'), source);
+      if (ownVersion) {
+        return ownVersion;
+      }
 
-        const entryPath = nodeRequire.resolve(source, { paths: [cwd] });
-        // Walk up from the entry file to the package's own package.json (the name check skips
-        // nested stubs like a dist/package.json); stop at the filesystem root.
-        for (let directory = path.dirname(entryPath); ; directory = path.dirname(directory)) {
-          const version = this.packageVersionAt(fs, path.join(directory, 'package.json'), source);
-          if (version) {
-            return version;
-          }
+      const entryPath = require.resolve(source, { paths: [cwd] });
+      // Walk up from the entry file to the package's own package.json (the name check skips
+      // nested stubs like a dist/package.json); stop at the filesystem root.
+      for (let directory = path.dirname(entryPath); ; directory = path.dirname(directory)) {
+        const version = this.packageVersionAt(path.join(directory, 'package.json'), source);
+        if (version) {
+          return version;
+        }
 
-          if (path.dirname(directory) === directory) {
-            break;
-          }
+        if (path.dirname(directory) === directory) {
+          break;
         }
-      } catch {
-        // Unresolvable from cwd — reported below.
       }
+    } catch {
+      // Unresolvable from cwd — reported below.
     }
 
     this.logger.warn({
@@ -674,7 +655,7 @@ export class SourceRecordSyncRunner {
   }
 
   /** The `version` of the package.json at `packageJsonPath` when it exists and names `source`. */
-  private packageVersionAt(fs: typeof import('fs'), packageJsonPath: string, source: string): string | undefined {
+  private packageVersionAt(packageJsonPath: string, source: string): string | undefined {
     if (!fs.existsSync(packageJsonPath)) {
       return undefined;
     }

package/source/index.ts

@@ -0,0 +1,9 @@
+/**
+ * `@proteinjs/db/source` — the server-only half of the source-record sync: the runner behind
+ * `Db.init`'s source-record leg. It reads package.json files off the booting process (the
+ * version stamp on every row it writes), so it never rides the package's browser index; a
+ * server's boot imports this subpath once, which registers the runner as the package's
+ * `SourceRecordSync` — the seam `Db.init` and the pre-schema-sync migration phase resolve through
+ * reflection. A test harness that runs one boot of the sync directly imports the runner from here.
+ */
+export * from './SourceRecordSyncRunner';

package/source.d.ts

@@ -0,0 +1,2 @@
+// Types counterpart of source.js — see that file for why this stub exists.
+export * from './dist/generated/source/index';

package/source.js

@@ -0,0 +1,4 @@
+// Node10/classic-resolution stub for the `./source` subpath, owned by reflection-build.
+// Consumers that bypass the exports map (node10 resolution, tsconfig paths mappings) resolve
+// this file path first, so every install shape loads the built dist — never sources.
+module.exports = require('./dist/generated/source/index.js');

package/src/Db.ts

@@ -12,7 +12,7 @@ import {
 import { ReverseCascadeEdgeIndex } from './ReverseCascadeEdgeIndex';
 import { Record, RecordSerializer, SerializedRecord } from './Record';
 import { Logger } from '@proteinjs/logger';
-import { SourceRecordSyncRunner } from './source/SourceRecordSyncRunner';
+import { getSourceRecordSync } from './source/SourceRecordSync';
 import { ParameterizationConfig, ParamType, QueryBuilder, Statement, StatementFactory } from '@proteinjs/db-query';
 import { QueryBuilderFactory } from './QueryBuilderFactory';
 import { StatementConfigFactory } from './StatementConfigFactory';
@@ -211,7 +211,9 @@ export class Db<R extends Record = Record> implements DbService<R> {
    *    backfill, which fails loudly over violating data); an immediate no-op unless a migration
    *    declares {@link Migration.preSchemaSync};
    * 3. schema sync — create/alter every registered table (the DDL);
-   * 4. source-record sync.
+   * 4. source-record sync — through {@link getSourceRecordSync}: the runner is server-only code
+   *    behind the `@proteinjs/db/source` subpath (the browser index never carries it), registered
+   *    by the server's one import of that subpath; a boot without it fails here, loudly.
    */
   async init(): Promise<void> {
     await this.dbDriver.createDbIfNotExists();
@@ -225,7 +227,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     const { MigrationRunner } = await import('./MigrationRunner');
     await new MigrationRunner().runPreSchemaSyncMigrations(this.dbDriver.getTableManager());
     await this.dbDriver.getTableManager().loadTables();
-    await new SourceRecordSyncRunner().load();
+    await getSourceRecordSync().load();
   }
 
   async tableExists<T extends R>(table: Table<T>): Promise<boolean> {

package/src/MigrationRunner.ts

@@ -2,7 +2,7 @@ import { Moment, moment } from './opt/moment';
 import { Db, getDb, getDbAsSystem } from './Db';
 import { Table } from './Table';
 import { SourceRecordRepo } from './source/SourceRecordRepo';
-import { SourceRecordSyncRunner } from './source/SourceRecordSyncRunner';
+import { getSourceRecordSync } from './source/SourceRecordSync';
 import { getSourceRecordLoaders } from './source/SourceRecord';
 import { MigrationRunnerService, getMigrationRunnerService } from './services/MigrationRunnerService';
 import { Migration, MigrationEstimate, MigrationTable } from './tables/MigrationTable';
@@ -195,7 +195,7 @@ export class MigrationRunner implements MigrationRunnerService {
     }
 
     await tableManager.loadTable(migrationTable);
-    await new SourceRecordSyncRunner().load(migrationTable);
+    await getSourceRecordSync().load(migrationTable);
     this.logger.info({
       message: `Running ${flagged.length} pre-schema-sync migration${flagged.length === 1 ? '' : 's'} before schema sync`,
       obj: { ids: flagged.map((migration) => migration.id) },

package/src/source/SourceRecordSync.ts

@@ -0,0 +1,54 @@
+import { Loadable, SourceRepository } from '@proteinjs/reflection';
+import type { Table } from '../Table';
+
+/** What one boot of the sync did to one source-record table. */
+export type SourceRecordTableLoadSummary = {
+  inserts: number;
+  updates: number;
+  unchanged: number;
+  adopted: number;
+  /**
+   * Declarations whose natural key is held by a row the sync does not own (written at runtime —
+   * a person's own row, say): refused for this boot, that row left exactly as it is (see
+   * {@link SourceRecordOptions.naturalKey}).
+   */
+  refused: number;
+  deletes: number;
+  removedUpdates: number;
+  /** Rows stamped by a newer version of their declaring package — left exactly as they are. */
+  skippedNewer: number;
+  /** Source-loaded rows with no owner stamp that no declaration in this build claims. */
+  unowned: number;
+};
+
+export type SourceRecordLoadSummary = { [tableName: string]: SourceRecordTableLoadSummary };
+
+/**
+ * The source-record sync a boot runs — the seam `Db.init` (and the pre-schema-sync migration
+ * phase) reach it through. Its one implementation, `SourceRecordSyncRunner`, is server-only code:
+ * it reads package.json files off the booting process to version-stamp every row, so it lives
+ * behind the `@proteinjs/db/source` subpath and this package's browser index never carries it
+ * (test/BrowserIndexNoNodeBuiltins.test.ts holds that line). A server imports
+ * `@proteinjs/db/source` once at boot, which registers the runner here through reflection; the
+ * browser index declares only this interface.
+ */
+export interface SourceRecordSync extends Loadable {
+  /** One boot of the sync, for every source-record table in the build — or for `onlyTable`. */
+  load(onlyTable?: Table<any>): Promise<SourceRecordLoadSummary>;
+}
+
+/**
+ * The registered sync — or a loud refusal naming the subpath that registers it. A boot never
+ * silently skips its source records: a server that has not imported `@proteinjs/db/source` fails
+ * here, at `Db.init`, with the fix in the message.
+ */
+export const getSourceRecordSync = (): SourceRecordSync => {
+  const sync = SourceRepository.get().object<SourceRecordSync>('@proteinjs/db/SourceRecordSync');
+  if (!sync) {
+    throw new Error(
+      `Unable to find a @proteinjs/db/SourceRecordSync implementation. The source-record sync is server-only code behind the '@proteinjs/db/source' subpath: import '@proteinjs/db/source' once in the server's boot (it registers SourceRecordSyncRunner), and the boot's source records load.`
+    );
+  }
+
+  return sync;
+};

package/test/BrowserIndexNoNodeBuiltins.test.ts

@@ -0,0 +1,123 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import webpack from 'webpack';
+
+/**
+ * THE LAW: this package's browser-facing index never reaches a Node builtin. `@proteinjs/db` is
+ * one package for both halves — the browser's Db talks through DbService, the server's through a
+ * driver — and its public entry (`dist/generated/index.js`, what a consumer's webpack bundles)
+ * must bundle for the browser as it stands; a consumer app has no business patching the
+ * library's reach with a `resolve.fallback`. The source-record sync (it reads package.json files
+ * off the booting process) is the server-only code that broke this line in db 1.55–1.58 — a
+ * webpack 5 client bundle met its `fs` and booted to nothing — and now lives behind the
+ * `@proteinjs/db/source` subpath. This guard holds the line for every module to come.
+ *
+ * Mechanics: webpack 5.88.2 — the consumer's bundler, at app-ui's version — bundles the built
+ * browser index for `target: 'web'` with this package's own dependencies external, so the only
+ * resolution left to fail is a Node builtin's, which webpack 5 refuses by name ("Module not
+ * found: Error: Can't resolve 'fs'"). It refuses as a WARNING when the reach sits in a try/catch
+ * (an optional dependency) — exactly how 1.58.0's runner reached `fs`, through a renamed
+ * `require` that esbuild never sees but webpack's parser tracks — so errors AND warnings must be
+ * empty. The module list then pins the subpath out of the graph by path.
+ *
+ * The one named exception: four encryption modules import `crypto` (since before 1.54.1), and
+ * consumers substitute a browser build for it (app-ui's webpack: `fallback.crypto:
+ * crypto-browserify`). Pinned to exactly those four files — a fifth reader of `crypto`, or any
+ * other builtin anywhere, is red.
+ */
+const packageDir = path.join(__dirname, '..');
+const BROWSER_INDEX = 'dist/generated/index.js';
+const SERVER_ONLY_SUBPATH = /(^|\/)dist\/source\//;
+const CRYPTO_READERS = [
+  'dist/src/encryption/DataKeyStore.js',
+  'dist/src/encryption/EncryptionEnvelope.js',
+  'dist/src/encryption/InMemoryMasterKeyProvider.js',
+  'dist/src/encryption/SearchTokenizer.js',
+];
+
+/** What one browser bundle of the index came to. */
+type Bundle = { errors: string[]; warnings: string[]; modules: string[]; cryptoReaders: string[] };
+
+/** `fs.rmSync` (Node 14.14+; this package's @types/node predates it). */
+const removeDirectory = (directory: string) =>
+  (fs as unknown as { rmSync(target: string, options: { recursive: true; force: true }): void }).rmSync(directory, {
+    recursive: true,
+    force: true,
+  });
+
+/** This package's dependencies: a consumer resolves those itself; never this bundle's concern. */
+const dependencies = (): string[] =>
+  Object.keys(JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8')).dependencies);
+
+const bundleBrowserIndex = (): Promise<Bundle> =>
+  new Promise((resolve, reject) => {
+    const names = dependencies();
+    const cryptoReaders = new Set<string>();
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'db-browser-index-'));
+    webpack(
+      {
+        mode: 'none',
+        target: 'web',
+        context: packageDir,
+        entry: path.join(packageDir, BROWSER_INDEX),
+        output: { path: outDir, filename: 'browser.js' },
+        externals: [
+          ({ request, contextInfo }, callback) => {
+            if (names.some((name) => request === name || !!request?.startsWith(`${name}/`))) {
+              return callback(undefined, `commonjs ${request}`);
+            }
+
+            // The crypto exception, pinned to its readers; every other builtin stays webpack's own refusal.
+            if (request && /^(node:)?crypto$/.test(request)) {
+              const issuer = path.relative(packageDir, contextInfo?.issuer ?? '');
+              cryptoReaders.add(issuer);
+              if (CRYPTO_READERS.includes(issuer)) {
+                return callback(undefined, `commonjs ${request}`);
+              }
+            }
+
+            callback();
+          },
+        ],
+      },
+      (error, stats) => {
+        removeDirectory(outDir);
+        if (error || !stats) {
+          return reject(error ?? new Error('webpack produced no stats'));
+        }
+
+        const json = stats.toJson({ all: false, errors: true, warnings: true, modules: true });
+        const line = ({ message, moduleName }: { message: string; moduleName?: string }) =>
+          `${message.split('\n')[0]} (${moduleName})`;
+        resolve({
+          errors: (json.errors ?? []).map(line),
+          warnings: (json.warnings ?? []).map(line),
+          modules: (json.modules ?? []).map((module) => module.name ?? ''),
+          cryptoReaders: Array.from(cryptoReaders).sort(),
+        });
+      }
+    );
+  });
+
+describe('the browser index (dist/generated/index.js) bundles for the browser', () => {
+  let bundle: Bundle;
+
+  beforeAll(async () => {
+    bundle = await bundleBrowserIndex();
+  }, 60000);
+
+  it('reaches no Node builtin: webpack resolved every module with only the dependencies external', () => {
+    expect(bundle.errors).toEqual([]);
+    expect(bundle.warnings).toEqual([]);
+  });
+
+  it('never imports the server-only source-record sync (the @proteinjs/db/source subpath)', () => {
+    expect(bundle.modules.length).toBeGreaterThan(0);
+    expect(bundle.modules.filter((module) => SERVER_ONLY_SUBPATH.test(module))).toEqual([]);
+  });
+
+  it('pins the crypto exception to exactly its four readers', () => {
+    expect(bundle.cryptoReaders).toEqual(CRYPTO_READERS.slice().sort());
+  });
+});

package/test/SourceRecordLoaderQualifiedName.test.ts

@@ -10,11 +10,12 @@ import { graphSerializer } from '@proteinjs/util';
  * name, so a second declaration of the name anywhere in the package's reflected sources leaves
  * which one the artifact records to the build's file order — and the loser disappears without
  * a trace. These tests read the artifacts the build wrote (`generated/index.ts` for the package
- * entry, `generated/test/index.ts` for the `./test` subpath, both built from `src/`) and assert
- * the name holds the declaration interface, not some other declaration that shares it.
+ * entry, `generated/test/index.ts` for the `./test` subpath, `generated/source/index.ts` for the
+ * `./source` subpath — each built over `src/`) and assert the name holds the declaration
+ * interface, not some other declaration that shares it.
  */
 const QUALIFIED_NAME = '@proteinjs/db/SourceRecordLoader';
-const ARTIFACTS = ['generated/index.ts', 'generated/test/index.ts'];
+const ARTIFACTS = ['generated/index.ts', 'generated/test/index.ts', 'generated/source/index.ts'];
 
 /** The fields of an emitted node value these tests read. */
 type EmittedDeclaration = { packageName: string; name: string; qualifiedName: string; sourceType: SourceType };

package/test/SourceRecordSyncRunner.test.ts

@@ -1,4 +1,4 @@
-import { SourceRecordSyncRunner } from '../src/source/SourceRecordSyncRunner';
+import { SourceRecordSyncRunner } from '../source/SourceRecordSyncRunner';
 
 /**
  * Covers the two helpers that drive SourceRecordSyncRunner's change-detection:

package/test/SourceRecordSyncSeam.test.ts

@@ -0,0 +1,140 @@
+import { SourceRepository } from '@proteinjs/reflection';
+import { Db, DbDriver } from '../src/Db';
+import { Table } from '../src/Table';
+import { TableManager } from '../src/schema/TableManager';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+import { SourceRecordLoadSummary, SourceRecordSync, getSourceRecordSync } from '../src/source/SourceRecordSync';
+import { SourceRecordSyncRunner } from '../source/SourceRecordSyncRunner';
+
+/**
+ * The seam between a boot and the source-record sync. `Db.init` (and the pre-schema-sync
+ * migration phase) run the sync through `getSourceRecordSync()` — reflection's one
+ * `@proteinjs/db/SourceRecordSync` — instead of importing the runner: the runner is server-only
+ * code behind `@proteinjs/db/source`, kept out of the browser index by
+ * test/BrowserIndexNoNodeBuiltins.test.ts. Three pins: a boot with no sync registered refuses,
+ * loudly, naming the subpath (never a silent boot without its source records); the subpath's
+ * built artifact registers the runner as that one implementation (the server road — exactly what
+ * a server's `import '@proteinjs/db/source'` runs); and `Db.init` reaches the registered sync
+ * after schema sync, as the whole-build boot (no table named).
+ */
+type SourceRepositoryInternals = {
+  objectCache: { [qualifiedName: string]: unknown[] };
+  namedObjectCache: { [qualifiedName: string]: { qualifiedName: string; packageName: string; object: unknown }[] };
+};
+const QUALIFIED_NAME = '@proteinjs/db/SourceRecordSync';
+const internals = () => SourceRepository.get() as unknown as SourceRepositoryInternals;
+/** Reflection memoizes each lookup (a refusal caches an empty answer): forget this seam's. */
+const forgetLookups = () => {
+  delete internals().objectCache[QUALIFIED_NAME];
+  delete internals().namedObjectCache[QUALIFIED_NAME];
+};
+
+describe('getSourceRecordSync — a boot without the server-only subpath refuses', () => {
+  beforeAll(async () => {
+    forgetLookups();
+    // The package's own entry, as every consumer's `import '@proteinjs/db'` runs it: the seam's
+    // interface is in the graph, and nothing implements it until the subpath is imported.
+    await import('../generated/index');
+  });
+  afterAll(forgetLookups);
+
+  it('throws, naming @proteinjs/db/source, when no SourceRecordSync is registered', () => {
+    expect(() => getSourceRecordSync()).toThrow(/Unable to find a @proteinjs\/db\/SourceRecordSync implementation/);
+    expect(() => getSourceRecordSync()).toThrow(/import '@proteinjs\/db\/source'/);
+  });
+});
+
+describe('the ./source subpath registers the runner (the server road)', () => {
+  beforeAll(async () => {
+    forgetLookups();
+    // The artifact the build wrote for the subpath — what `import '@proteinjs/db/source'` runs on a server.
+    await import('../generated/source');
+  });
+  afterAll(forgetLookups);
+
+  it('resolves SourceRecordSyncRunner as the one @proteinjs/db/SourceRecordSync', () => {
+    expect(getSourceRecordSync()).toBeInstanceOf(SourceRecordSyncRunner);
+    expect(SourceRepository.get().objects<SourceRecordSync>(QUALIFIED_NAME)).toHaveLength(1);
+  });
+});
+
+describe('Db.init runs the registered sync after schema sync (the whole-build boot)', () => {
+  /** The boot's legs in the order they ran: schema sync, then the sync with the table it was given. */
+  const legs: { leg: 'schema' | 'sync'; onlyTable?: string }[] = [];
+
+  class RecordingSync implements SourceRecordSync {
+    async load(onlyTable?: Table<any>): Promise<SourceRecordLoadSummary> {
+      legs.push({ leg: 'sync', onlyTable: onlyTable?.name });
+      return {};
+    }
+  }
+
+  /** Accepts the boot's schema leg and records it; no database behind it. */
+  class BootDriver implements DbDriver {
+    getDbName(): string {
+      return 'test';
+    }
+
+    async createDbIfNotExists(): Promise<void> {}
+
+    async createDb(): Promise<void> {}
+
+    async dropDb(): Promise<void> {}
+
+    getTableManager(): TableManager {
+      return {
+        loadTables: async () => {
+          legs.push({ leg: 'schema' });
+        },
+      } as unknown as TableManager;
+    }
+
+    async runQuery(): Promise<never[]> {
+      return [];
+    }
+
+    async runDml(): Promise<number> {
+      return 0;
+    }
+
+    async runTransaction<T>(fn: (transaction: unknown) => Promise<T>): Promise<T> {
+      return await fn({ id: 'transaction' });
+    }
+
+    getOperationDeadlineMs(): number {
+      return 1000;
+    }
+  }
+
+  class BootTransactionContextFactory implements DefaultTransactionContextFactory {
+    private context: TransactionContextData = {};
+
+    getTransactionContext(): TransactionContextData {
+      return this.context;
+    }
+
+    async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+      const previous = this.context;
+      this.context = context;
+      try {
+        return await fn();
+      } finally {
+        this.context = previous;
+      }
+    }
+  }
+
+  beforeAll(() => {
+    forgetLookups();
+    // Registered the way the subpath's artifact registers the runner: one named SourceRecordSync.
+    internals().namedObjectCache[QUALIFIED_NAME] = [
+      { qualifiedName: '@test/RecordingSync', packageName: '@test', object: new RecordingSync() },
+    ];
+  });
+  afterAll(forgetLookups);
+
+  it('reaches the sync through the seam, after the schema sync, for the whole build', async () => {
+    await new Db(new BootDriver(), undefined, new BootTransactionContextFactory()).init();
+    expect(legs).toEqual([{ leg: 'schema' }, { leg: 'sync', onlyTable: undefined }]);
+  });
+});

package/test/reusable/SourceRecordSyncTests.ts

@@ -13,7 +13,7 @@ import {
   withSourceRecordColumns,
 } from '@proteinjs/db';
 import type { DefaultTransactionContextFactory } from '@proteinjs/db';
-import { SourceRecordSyncRunner } from '../../src/source/SourceRecordSyncRunner';
+import { SourceRecordSyncRunner } from '../../source/SourceRecordSyncRunner';
 import { TableWatcherRunner } from '../../src/TableWatcherRunner';
 import { DbTestEnvironment } from '../util/DbTestEnvironment';
 import {

package/tsconfig.json

@@ -20,8 +20,9 @@
     "paths": {
       "@proteinjs/db": ["index.ts"],
       "@proteinjs/db/*": ["src/*"],
-      "@proteinjs/db/test": ["test/index.ts"]
+      "@proteinjs/db/test": ["test/index.ts"],
+      "@proteinjs/db/source": ["source/index.ts"]
     }
   },
-  "exclude": ["node_modules", "dist", "test.js", "test.d.ts"]
+  "exclude": ["node_modules", "dist", "test.js", "test.d.ts", "source.js", "source.d.ts"]
 }

package/dist/src/source/SourceRecordSyncRunner.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SourceRecordSyncRunner.d.ts","sourceRoot":"","sources":["../../../src/source/SourceRecordSyncRunner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAkBjC,gEAAgE;AAChE,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,YAAY,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG,4BAA4B,CAAA;CAAE,CAAC;AAE5F,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAA+C;IAE7D,+FAA+F;IAC/F,OAAO,CAAC,cAAc,CAAyC;IAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC;IA0JpE;;;;;;;;;OASG;YACW,gBAAgB;IA2D9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,kCAAkC;IA0BhD;;;;;;OAMG;YACW,YAAY;IAkB1B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA+CvB;;;;;;;;;;;;;;;;;;;OAmBG;YACW,UAAU;IAwBxB;;;OAGG;YACW,eAAe;IAmB7B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gBAAgB;IAkDxB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,kBAAkB;IAmB1B,mGAAmG;IACnG,OAAO,CAAC,aAAa;IAQrB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,oBAAoB;IAyC5B,gGAAgG;IAChG,OAAO,CAAC,gBAAgB;IASxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;IAapB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CA4DxB"}