@semilayer/bridge-resolver 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SemiLayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @semilayer/bridge-resolver
+
+Built-in bridge registry and runtime resolver for [SemiLayer](https://semilayer.com). Ships the first-party PostgreSQL adapter and provides an extension point for community and enterprise bridges.
+
+## Installation
+
+```bash
+npm install @semilayer/bridge-resolver
+# or
+pnpm add @semilayer/bridge-resolver
+```
+
+## Usage
+
+```typescript
+import { resolveBridge } from '@semilayer/bridge-resolver'
+
+// Resolve the built-in Postgres bridge
+const PostgresBridge = resolveBridge('@semilayer/bridge-postgres')
+const bridge = new PostgresBridge({ url: process.env.DATABASE_URL })
+await bridge.connect()
+```
+
+## Community Bridges
+
+Community bridges are registered at startup via `registerBridge()`. They do not need to be merged into this package to be used.
+
+```typescript
+import { registerBridge, resolveBridge } from '@semilayer/bridge-resolver'
+import { MySQLBridge } from '@community/bridge-mysql'
+import { MongoBridge } from '@community/bridge-mongo'
+
+// Register at worker startup, before the first ingest job runs
+registerBridge('@community/bridge-mysql', MySQLBridge)
+registerBridge('@community/bridge-mongo', MongoBridge)
+
+// ...later, the resolver finds them by name
+const Ctor = resolveBridge('@community/bridge-mysql')
+```
+
+Custom bridges take priority over built-ins with the same name — useful for testing or overriding behavior in enterprise deployments.
+
+## API
+
+### `resolveBridge(name): BridgeConstructor`
+
+Looks up a bridge by name. Checks custom registrations first, then built-in bridges. Throws if no bridge matches the given name.
+
+### `registerBridge(name, ctor): void`
+
+Registers a bridge constructor under a name. The name is the identifier users reference in their SemiLayer config (`sources.main.bridge = '@community/bridge-mysql'`).
+
+### `listBridges(): string[]`
+
+Returns all registered bridge names (built-in + custom), deduplicated.
+
+### `clearCustomBridges(): void`
+
+Removes all custom bridges. Built-in bridges remain registered. Primarily useful in tests.
+
+## Built-in Bridges
+
+| Name | Package | Database |
+|------|---------|----------|
+| `@semilayer/bridge-postgres` | [`@semilayer/bridge-postgres`](https://github.com/semilayer/bridge-postgres) | PostgreSQL (and wire-compatible variants — Neon, Supabase, CockroachDB, ...) |
+
+More first-party bridges will be added over time. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the process to propose adding a new bridge to the built-in registry.
+
+## Writing a New Bridge
+
+See the [bridge authoring guide](https://semilayer.dev/guides/bridges) and the [`@semilayer/bridge-postgres`](https://github.com/semilayer/bridge-postgres) reference implementation.
+
+Every bridge must:
+
+1. Implement the `Bridge` interface from `@semilayer/core`
+2. Pass the compliance test suite from `@semilayer/bridge-sdk`:
+   ```typescript
+   import { createBridgeTestSuite } from '@semilayer/bridge-sdk'
+   import { MyBridge } from './src/index.js'
+
+   createBridgeTestSuite(() => new MyBridge({ /* config */ }))
+   ```
+3. Publish to npm as its own package — either under your own scope (`@acme/bridge-mydb`) or request the `@semilayer` scope if it becomes first-party
+
+You **do not** need to PR into this repo to publish a community bridge. Publish your package and users can register it with `registerBridge()` at runtime.
+
+If you want your bridge to ship as a built-in (so users don't need to call `registerBridge()`), open an issue here first to discuss. We're selective about what lands in the built-in registry.
+
+## Requirements
+
+- Node.js 20+
+- `@semilayer/core` (peer-compatible version)
+- `@semilayer/bridge-postgres` (bundled as a dependency)
+
+## Links
+
+- [SemiLayer documentation](https://semilayer.dev)
+- [Bridge authoring guide](https://semilayer.dev/guides/bridges)
+- [`@semilayer/bridge-postgres`](https://github.com/semilayer/bridge-postgres) — reference implementation
+- [Contributing](./CONTRIBUTING.md)
+
+## License
+
+MIT © SemiLayer

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { BridgeConstructor } from '@semilayer/core';
+
+/**
+ * Register a custom bridge at runtime.
+ *
+ * Used to add community or enterprise bridges to the resolver without
+ * modifying the built-in registry. Custom bridges take priority over
+ * built-in bridges with the same name.
+ *
+ * @example
+ * ```ts
+ * import { registerBridge } from '@semilayer/bridge-resolver'
+ * import { MySQLBridge } from '@community/bridge-mysql'
+ *
+ * registerBridge('@community/bridge-mysql', MySQLBridge)
+ * ```
+ */
+declare function registerBridge(name: string, ctor: BridgeConstructor): void;
+/**
+ * Clear all custom bridges (useful in tests).
+ */
+declare function clearCustomBridges(): void;
+/**
+ * Resolve a bridge constructor by name.
+ * Checks custom bridges first, then built-in registry.
+ *
+ * @throws if the bridge is not registered
+ */
+declare function resolveBridge(name: string): BridgeConstructor;
+/**
+ * List all available bridge names (built-in + custom).
+ */
+declare function listBridges(): string[];
+
+export { clearCustomBridges, listBridges, registerBridge, resolveBridge };

package/dist/index.js

@@ -0,0 +1,33 @@
+// src/index.ts
+import { PostgresBridge } from "@semilayer/bridge-postgres";
+var BUILT_IN_BRIDGES = {
+  "@semilayer/bridge-postgres": PostgresBridge
+};
+var customBridges = {};
+function registerBridge(name, ctor) {
+  customBridges[name] = ctor;
+}
+function clearCustomBridges() {
+  customBridges = {};
+}
+function resolveBridge(name) {
+  const Ctor = customBridges[name] ?? BUILT_IN_BRIDGES[name];
+  if (!Ctor) {
+    const available = [
+      ...Object.keys(BUILT_IN_BRIDGES),
+      ...Object.keys(customBridges)
+    ].join(", ");
+    throw new Error(`Unknown bridge: "${name}". Available: ${available}`);
+  }
+  return Ctor;
+}
+function listBridges() {
+  return [.../* @__PURE__ */ new Set([...Object.keys(BUILT_IN_BRIDGES), ...Object.keys(customBridges)])];
+}
+export {
+  clearCustomBridges,
+  listBridges,
+  registerBridge,
+  resolveBridge
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { BridgeConstructor } from '@semilayer/core'\nimport { PostgresBridge } from '@semilayer/bridge-postgres'\n\nconst BUILT_IN_BRIDGES: Record<string, BridgeConstructor> = {\n  '@semilayer/bridge-postgres': PostgresBridge,\n}\n\nlet customBridges: Record<string, BridgeConstructor> = {}\n\n/**\n * Register a custom bridge at runtime.\n *\n * Used to add community or enterprise bridges to the resolver without\n * modifying the built-in registry. Custom bridges take priority over\n * built-in bridges with the same name.\n *\n * @example\n * ```ts\n * import { registerBridge } from '@semilayer/bridge-resolver'\n * import { MySQLBridge } from '@community/bridge-mysql'\n *\n * registerBridge('@community/bridge-mysql', MySQLBridge)\n * ```\n */\nexport function registerBridge(name: string, ctor: BridgeConstructor): void {\n  customBridges[name] = ctor\n}\n\n/**\n * Clear all custom bridges (useful in tests).\n */\nexport function clearCustomBridges(): void {\n  customBridges = {}\n}\n\n/**\n * Resolve a bridge constructor by name.\n * Checks custom bridges first, then built-in registry.\n *\n * @throws if the bridge is not registered\n */\nexport function resolveBridge(name: string): BridgeConstructor {\n  const Ctor = customBridges[name] ?? BUILT_IN_BRIDGES[name]\n  if (!Ctor) {\n    const available = [\n      ...Object.keys(BUILT_IN_BRIDGES),\n      ...Object.keys(customBridges),\n    ].join(', ')\n    throw new Error(`Unknown bridge: \"${name}\". Available: ${available}`)\n  }\n  return Ctor\n}\n\n/**\n * List all available bridge names (built-in + custom).\n */\nexport function listBridges(): string[] {\n  return [...new Set([...Object.keys(BUILT_IN_BRIDGES), ...Object.keys(customBridges)])]\n}\n"],"mappings":";AACA,SAAS,sBAAsB;AAE/B,IAAM,mBAAsD;AAAA,EAC1D,8BAA8B;AAChC;AAEA,IAAI,gBAAmD,CAAC;AAiBjD,SAAS,eAAe,MAAc,MAA+B;AAC1E,gBAAc,IAAI,IAAI;AACxB;AAKO,SAAS,qBAA2B;AACzC,kBAAgB,CAAC;AACnB;AAQO,SAAS,cAAc,MAAiC;AAC7D,QAAM,OAAO,cAAc,IAAI,KAAK,iBAAiB,IAAI;AACzD,MAAI,CAAC,MAAM;AACT,UAAM,YAAY;AAAA,MAChB,GAAG,OAAO,KAAK,gBAAgB;AAAA,MAC/B,GAAG,OAAO,KAAK,aAAa;AAAA,IAC9B,EAAE,KAAK,IAAI;AACX,UAAM,IAAI,MAAM,oBAAoB,IAAI,iBAAiB,SAAS,EAAE;AAAA,EACtE;AACA,SAAO;AACT;AAKO,SAAS,cAAwB;AACtC,SAAO,CAAC,GAAG,oBAAI,IAAI,CAAC,GAAG,OAAO,KAAK,gBAAgB,GAAG,GAAG,OAAO,KAAK,aAAa,CAAC,CAAC,CAAC;AACvF;","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@semilayer/bridge-resolver",
+  "version": "1.0.0",
+  "description": "SemiLayer bridge resolver — built-in registry and dynamic bridge loading for first-party and community database adapters",
+  "keywords": [
+    "semilayer",
+    "bridge",
+    "resolver",
+    "registry",
+    "adapter"
+  ],
+  "license": "MIT",
+  "author": "SemiLayer",
+  "homepage": "https://github.com/semilayer/bridge-resolver#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/semilayer/bridge-resolver.git"
+  },
+  "bugs": {
+    "url": "https://github.com/semilayer/bridge-resolver/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@semilayer/bridge-postgres": "^1.0.0",
+    "@semilayer/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}