feat: add centralized datasource mapping for package/namespace-level routing by Claude · Pull Request #1143 · objectstack-ai/framework

Claude · 2026-04-14T12:09:40Z

Implements centralized datasource routing configuration to eliminate per-object datasource field configuration. Enables routing by namespace, package ID, or glob patterns with priority-based resolution.

Changes

Schema Definitions

DatasourceMappingRuleSchema in packages/spec/src/stack.zod.ts: Defines routing rules supporting namespace, package, objectPattern (glob), priority, and default fallback
datasourceMapping field added to ObjectStackDefinitionSchema: Accepts array of routing rules
defaultDatasource field added to ManifestSchema: Package-level default datasource configuration

ObjectQL Engine

4-tier resolution priority in getDriver():
1. Object's explicit datasource field
2. datasourceMapping rules (evaluated by priority)
3. Package's defaultDatasource
4. Global default driver
resolveDatasourceFromMapping(): Evaluates rules with namespace/package/pattern matching
matchPattern(): Glob-style pattern matching (*, ? wildcards)
setDatasourceMapping(): Public API to configure rules
Manifest registry: Stores package manifests for defaultDatasource lookup

Runtime Integration

AppPlugin: Automatically calls ql.setDatasourceMapping() when stack contains datasourceMapping

Testing & Documentation

Comprehensive test suite covering namespace, pattern, priority, default, and override scenarios
Complete usage documentation with examples and migration guide

Example Usage

export default defineStack({
  plugins: [
    new ObjectQLPlugin(),
    new DriverPlugin(new TursoDriver({ url: 'file:./data/system.db' }), 'turso'),
    new DriverPlugin(new InMemoryDriver(), 'memory'),
    new AppPlugin(CrmApp),
  ],
  
  datasourceMapping: [
    // System objects → Turso (persistent)
    { objectPattern: 'sys_*', datasource: 'turso' },
    { namespace: 'auth', datasource: 'turso' },
    
    // CRM → Memory (dev/test)
    { namespace: 'crm', datasource: 'memory' },
    
    // Default → Turso
    { default: true, datasource: 'turso' },
  ],
});

Architecture

Inspired by Django's Database Router and Kubernetes StorageClass patterns. Resolution priority ensures explicit object configuration always wins, with centralized mapping providing sensible defaults for packages/namespaces.

Pattern matching enables batch configuration: sys_* routes all system objects, temp_* routes temporary objects, etc.

Fully backward compatible—existing explicit datasource fields work unchanged.

…routing Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/d2dcf3f2-8178-4b63-bed4-5340d2e6df15 Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel · 2026-04-14T12:09:47Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-demo	Error		Apr 14, 2026 0:09am
spec	Building	Preview, Comment	Apr 14, 2026 0:09am

Copilot

Pull request overview

Adds a centralized datasource routing mechanism to ObjectStack so stacks can route objects to drivers by namespace/package/pattern, reducing per-object datasource configuration and enabling package-level defaults.

Changes:

Introduces datasourceMapping and DatasourceMappingRuleSchema to the stack definition schema.
Extends package manifests with defaultDatasource and updates ObjectQL driver resolution to use a 4-tier priority.
Adds runtime wiring + tests + standalone documentation for the feature.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
packages/spec/src/stack.zod.ts	Adds `DatasourceMappingRuleSchema` and `datasourceMapping` to stack schema.
packages/spec/src/kernel/manifest.zod.ts	Adds `defaultDatasource` to manifests for package-level defaults.
packages/objectql/src/engine.ts	Implements mapping + manifest-aware driver selection; adds mapping setter and manifest registry.
packages/runtime/src/app-plugin.ts	Attempts to configure ObjectQL mapping during app plugin startup.
packages/objectql/src/datasource-mapping.test.ts	Adds tests intended to cover namespace/pattern/priority/default/override behavior.
DATASOURCE_MAPPING.md	User-facing documentation and migration guidance for datasource mapping.
IMPLEMENTATION_SUMMARY.md	High-level implementation recap and rationale.

Copilot · 2026-04-14T12:18:56Z

packages/objectql/src/engine.ts

+      // 1. Match by namespace
+      if (rule.namespace && object?.namespace === rule.namespace) {
+        return rule.datasource;
+      }


Namespace-based routing checks object?.namespace, but SchemaRegistry.registerObject() does not inject the manifest namespace into the object definition (examples typically omit object.namespace). This means namespace rules won’t match for most objects. Consider deriving the namespace from the resolved object’s FQN (e.g., parse object.name) or from registry contributor metadata instead of relying on object.namespace.

Copilot · 2026-04-14T12:18:57Z

packages/objectql/src/engine.ts

+    // 3. Check package's defaultDatasource
+    if (object?.packageId) {
+      const manifest = this.manifests.get(object.packageId);
+      if (manifest?.defaultDatasource && manifest.defaultDatasource !== 'default') {


This manifest-level fallback uses object?.packageId, but ServiceObject does not carry a packageId, so defaultDatasource from manifests will never be applied. Consider deriving the owning packageId from SchemaRegistry contributor metadata (e.g., owner for object.name) before reading this.manifests.

Copilot · 2026-04-14T12:18:57Z

packages/objectql/src/datasource-mapping.test.ts

+    // Test that it uses memory driver
+    const result = await engine.create('account', { name: 'Test Account' });
+    expect(result).toBeDefined();


This test calls engine.create(objectName, data), but ObjectQL does not expose a create method on the engine itself (only insert() on the engine and create() on ObjectRepository). This will fail to compile/run; use engine.insert(...) (or create a scoped repository) instead.

Copilot · 2026-04-14T12:18:57Z

packages/objectql/src/engine.ts

+      if (manifest?.defaultDatasource && manifest.defaultDatasource !== 'default') {
+        if (this.drivers.has(manifest.defaultDatasource)) {
+          this.logger.debug('Resolved datasource from package manifest', {
+            object: objectName,
+            package: object.packageId,


If manifest.defaultDatasource is configured (and not 'default') but the driver isn’t registered, this currently falls through to the global default without error. Consider throwing here as well to surface configuration mistakes early.

Copilot · 2026-04-14T12:18:57Z

packages/spec/src/stack.zod.ts

+export const DatasourceMappingRuleSchema = z.object({
+  /**
+   * Match by namespace (e.g., 'crm', 'auth', 'todo')
+   * Objects with this namespace will use the specified datasource.
+   */


DatasourceMappingRuleSchema doesn’t prevent rules where all selectors are omitted (namespace, package, objectPattern, default all undefined). Such rules can never match and likely indicate a config error. Consider adding a schema refinement requiring at least one selector (and optionally constraining default: true to not be combined with other selectors if you want defaults to be unambiguous).

Copilot · 2026-04-14T12:18:59Z

packages/spec/src/kernel/manifest.zod.ts

+   * This provides package-level datasource configuration without needing to
+   * specify it on every individual object.
+   *
+   * @example "memory"  // Use in-memory driver for all package objects
+   * @example "turso"   // Use Turso/LibSQL for all package objects
+   */
+  defaultDatasource: z.string().optional().default('default')
+    .describe('Default datasource for all objects in this package'),


defaultDatasource is described as optional, but .optional().default('default') makes the post-parse output always include a value and changes the inferred ObjectStackManifest type. If the intent is “unset means global default”, consider removing the Zod default and treating undefined as 'default' in resolver logic, or adjust docs/types accordingly.

Suggested change

* This provides package-level datasource configuration without needing to

* specify it on every individual object.

*

* @example "memory" // Use in-memory driver for all package objects

* @example "turso" // Use Turso/LibSQL for all package objects

*/

defaultDatasource: z.string().optional().default('default')

.describe('Default datasource for all objects in this package'),

* If omitted in manifest input, parsing will normalize this field to `"default"`.

* As a result, parsed `ObjectStackManifest` values always include a concrete

* `defaultDatasource` string.

*

* This provides package-level datasource configuration without needing to

* specify it on every individual object.

*

* @example "memory" // Use in-memory driver for all package objects

* @example "turso" // Use Turso/LibSQL for all package objects

* @example "default" // Use the platform's default datasource

*/

defaultDatasource: z.string().default('default')

.describe('Default datasource for all objects in this package; defaults to "default" when omitted'),

Copilot · 2026-04-14T12:18:59Z

packages/objectql/src/engine.ts

+      // 2. Match by package ID
+      if (rule.package && object?.packageId === rule.package) {
+        return rule.datasource;
+      }


Package-based routing checks object?.packageId, but ServiceObject does not include packageId, so this condition will never match. Consider looking up the owning package via SchemaRegistry.getObjectOwner(fqn)?.packageId (or similar registry metadata) and compare that to rule.package.

Copilot · 2026-04-14T12:18:59Z

packages/objectql/src/engine.ts

+  }>) {
+    this.datasourceMapping = rules;
+    this.logger.info('Datasource mapping rules configured', {
+      ruleCount: rules.length
+    });


resolveDatasourceFromMapping() clones/sorts rules and matchPattern() recompiles regexes during driver resolution, which happens on every CRUD call. Consider pre-sorting (and optionally precompiling pattern matchers) once inside setDatasourceMapping() to avoid repeated allocations and sorting overhead.

Copilot · 2026-04-14T12:19:00Z

packages/spec/src/stack.zod.ts

+   * Rules are evaluated in order (or by priority if specified). First match wins.
+   * If no match, falls back to object's explicit `datasource` field, then 'default'.


The datasourceMapping docstring states “If no match, falls back to object's explicit datasource field, then 'default'”, but the engine resolution order is the opposite (explicit object.datasource wins first, then mapping, then package default, then global). Please update this comment to match the actual resolution priority to avoid misleading users.

Suggested change

* Rules are evaluated in order (or by priority if specified). First match wins.

* If no match, falls back to object's explicit `datasource` field, then 'default'.

* Datasource resolution priority is:

* 1. Object's explicit `datasource` field

* 2. `datasourceMapping` rules, evaluated in order (or by priority if specified); first match wins

* 3. Package-level default datasource

* 4. Global/default datasource

Copilot · 2026-04-14T12:19:00Z

packages/runtime/src/app-plugin.ts

+        // Configure datasourceMapping if provided in the stack definition
+        if (this.bundle.datasourceMapping && Array.isArray(this.bundle.datasourceMapping)) {
+            ctx.logger.info('Configuring datasource mapping rules', {
+                appId,
+                ruleCount: this.bundle.datasourceMapping.length


datasourceMapping is applied from this.bundle.datasourceMapping (the app bundle), but the PR description/examples put datasourceMapping on the host stack (the one that lists plugins). In host/aggregator configs this won’t configure routing at all. Consider moving this wiring to host bootstrap (e.g., Runtime/ObjectQLPlugin using the root stack config) or explicitly passing host-level rules into AppPlugin instances.

feat: add centralized datasource mapping for package/namespace-level …

f85f957

…routing Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/d2dcf3f2-8178-4b63-bed4-5340d2e6df15 Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Claude AI assigned Claude and hotlong Apr 14, 2026

Claude created this pull request from a session on behalf of hotlong April 14, 2026 12:09 View session

hotlong marked this pull request as ready for review April 14, 2026 12:09

Copilot AI review requested due to automatic review settings April 14, 2026 12:09

github-actions bot added documentation Improvements or additions to documentation tests size/l labels Apr 14, 2026

Copilot started reviewing on behalf of hotlong April 14, 2026 12:10 View session

hotlong merged commit fecea08 into main Apr 14, 2026
10 of 14 checks passed

vercel bot deployed to Preview – spec April 14, 2026 12:13 View deployment

Copilot AI reviewed Apr 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add centralized datasource mapping for package/namespace-level routing#1143

feat: add centralized datasource mapping for package/namespace-level routing#1143
hotlong merged 1 commit intomainfrom
claude/use-different-data-sources

Claude AI commented Apr 14, 2026

Uh oh!

vercel bot commented Apr 14, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		* Rules are evaluated in order (or by priority if specified). First match wins.
		* If no match, falls back to object's explicit `datasource` field, then 'default'.

-   * Rules are evaluated in order (or by priority if specified). First match wins.
-   * If no match, falls back to object's explicit `datasource` field, then 'default'.
+   * Datasource resolution priority is:
+   * 1. Object's explicit `datasource` field
+   * 2. `datasourceMapping` rules, evaluated in order (or by priority if specified); first match wins
+   * 3. Package-level default datasource
+   * 4. Global/default datasource

Conversation

Claude AI commented Apr 14, 2026

Changes

Schema Definitions

ObjectQL Engine

Runtime Integration

Testing & Documentation

Example Usage

Architecture

Uh oh!

vercel bot commented Apr 14, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants