Named import mappings: wire defineMapping into the import path (#2611) (#2629)

Author: os-zhuang

.changeset/named-import-mappings.md

@@ -0,0 +1,6 @@
+---
+'@objectstack/rest': minor
+'@objectstack/spec': minor
+---
+
+feat(rest,spec): named import mappings (#2611) — `POST /data/:object/import` accepts `mappingName`, resolving a registered `defineMapping` artifact (stack `mappings:`) and applying its fieldMapping pipeline (rename + constant/map/split/join; lookup delegates to the built-in reference resolution) as a strict projection before coercion. The artifact's `mode`/`upsertKey` serve as writeMode/matchFields defaults; explicit request values win. Errors are loud and specific: `MAPPING_NOT_FOUND`, `MAPPING_TARGET_MISMATCH`, `MAPPING_FORMAT_MISMATCH`, `CONFLICTING_MAPPING` (mutually exclusive with the inline rename), and `UNSUPPORTED_TRANSFORM` for `javascript` (no server-side sandbox — never silently skipped). `defineStack` cross-reference validation now rejects mappings targeting undefined objects and `javascript` transforms at build time.

content/docs/references/api/metadata.mdx

@@ -314,7 +314,7 @@ Metadata query with filtering, sorting, and pagination
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **types** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
+| **types** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'mapping' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
 | **namespaces** | `string[]` | optional | Filter by namespaces |
 | **packageId** | `string` | optional | Filter by owning package |
 | **search** | `string` | optional | Full-text search query |
@@ -349,7 +349,7 @@ Metadata query with filtering, sorting, and pagination
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
+| **type** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'mapping' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
 | **name** | `string` | ✅ | Item name (snake_case) |
 | **data** | `Record<string, any>` | ✅ | Metadata payload |
 | **namespace** | `string` | optional | Optional namespace |

content/docs/references/kernel/metadata-plugin.mdx

@@ -130,7 +130,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **event** | `Enum<'metadata.registered' \| 'metadata.updated' \| 'metadata.unregistered' \| 'metadata.validated' \| 'metadata.deployed' \| 'metadata.overlay.applied' \| 'metadata.overlay.removed' \| 'metadata.imported' \| 'metadata.exported'>` | ✅ | Event type |
-| **metadataType** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
+| **metadataType** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'mapping' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type |
 | **name** | `string` | ✅ | Metadata item name |
 | **namespace** | `string` | optional | Namespace |
 | **packageId** | `string` | optional | Owning package ID |
@@ -147,7 +147,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **types** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
+| **types** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'mapping' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>[]` | optional | Filter by metadata types |
 | **namespaces** | `string[]` | optional | Filter by namespaces |
 | **packageId** | `string` | optional | Filter by owning package |
 | **search** | `string` | optional | Full-text search query |
@@ -185,6 +185,7 @@ const result = MetadataBulkRegisterRequest.parse(data);
 * `validation`
 * `hook`
 * `seed`
+* `mapping`
 * `view`
 * `page`
 * `dashboard`

examples/app-showcase/objectstack.config.ts

@@ -41,6 +41,7 @@ import { allPortals } from './src/ui/portals/index.js';
 import { ShowcaseSeedData } from './src/data/seed/index.js';
 import { allCubes } from './src/data/analytics/showcase.cube.js';
 import { allObjectExtensions } from './src/data/extensions/account.extension.js';
+import { allMappings } from './src/data/mappings/index.js';
 
 // Ambient `process` for the env-var overrides below — the showcase tsconfig
 // doesn't pull in `@types/node`, but the CLI provides the real `process` at
@@ -164,6 +165,9 @@ export default defineStack({
   // (`/api/v1/analytics/*`) — no `requires` token needed; the CLI always
   // loads it and registers these cubes (see src/data/analytics/).
   analyticsCubes: allCubes,
+  // Named import mappings (#2611) — resolved by the import endpoint via
+  // `mappingName` (see src/data/mappings/).
+  mappings: allMappings,
 
   // UI
   apps: [ShowcaseApp],

examples/app-showcase/src/coverage.ts

@@ -74,6 +74,12 @@ export const KIND_COVERAGE: Record<MetadataType, KindCoverage> = {
   },
   hook: { status: 'demonstrated', files: ['src/data/hooks/index.ts'] },
   seed: { status: 'demonstrated', files: ['src/data/seed/index.ts'] },
+  mapping: {
+    status: 'demonstrated',
+    files: ['src/data/mappings/index.ts'],
+    notes:
+      'Named import mapping resolved via mappingName at POST /data/:object/import (#2611); promoted to a registry kind per the ADR-0088 admission test.',
+  },
 
   // ── ui ──
   view: { status: 'demonstrated', files: ['src/ui/views/task.view.ts', 'src/ui/views/project.view.ts'] },
@@ -165,12 +171,6 @@ export const STACK_COLLECTION_COVERAGE: Record<string, KindCoverage> = {
     notes:
       'Declarative ApiEndpoint metadata (object_operation + flow targets), executed by the runtime dispatcher (handleApiEndpoint). Complements the code-mounted endpoint in src/system/server/ (router kind stays waived: code-only).',
   },
-  mappings: {
-    status: 'waived',
-    reason:
-      'defineMapping artifacts are registered but never consumed — the REST import path only accepts an inline per-request mapping, so a stack-level mapping is inert.',
-    issue: 'https://github.com/objectstack-ai/framework/issues/2611',
-  },
   connectors: {
     status: 'waived',
     reason:

examples/app-showcase/src/data/mappings/index.ts

@@ -0,0 +1,41 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineMapping } from '@objectstack/spec';
+
+/**
+ * Named import mapping (#2611) — the reusable, governed counterpart of the
+ * import wizard's one-off inline rename. This one models the classic
+ * enterprise case: a marketing tool exports leads weekly with ITS column
+ * names and ITS channel codes; the mapping is defined once, ships with the
+ * package, and every import (human or scheduled job) references it by name:
+ *
+ *   POST /api/v1/data/showcase_inquiry/import
+ *   { "format": "csv", "csv": "...", "mappingName": "showcase_inquiry_feed" }
+ *
+ * mode/upsertKey make re-importing the same file idempotent (dedupe on
+ * email) — no writeMode/matchFields needed on the request. The `map`
+ * transform translates the source system's channel codes; the import
+ * pipeline's own coercion + reference resolution still run afterwards.
+ */
+export const InquiryFeedMapping = defineMapping({
+  name: 'showcase_inquiry_feed',
+  label: 'Inquiry feed (marketing CSV)',
+  sourceFormat: 'csv',
+  targetObject: 'showcase_inquiry',
+  fieldMapping: [
+    { source: 'Full Name', target: 'name' },
+    { source: 'E-mail', target: 'email' },
+    { source: 'Company', target: 'company' },
+    { source: 'Message', target: 'message' },
+    {
+      source: 'Channel',
+      target: 'source',
+      transform: 'map',
+      params: { valueMap: { Webform: 'website', 'Partner Referral': 'referral' } },
+    },
+  ],
+  mode: 'upsert',
+  upsertKey: ['email'],
+});
+
+export const allMappings = [InquiryFeedMapping];

examples/app-showcase/src/docs/showcase_tour_data.md

@@ -45,11 +45,17 @@ object: showcase_project
 name: project_status_flow
 ```
 
-## Hooks & seed data
+## Hooks, seed data & import mappings
 
 - `src/data/hooks/` — data-layer lifecycle hooks (before/after CRUD).
 - `src/data/seed/` — the seed dataset that makes every view render something
   real on first boot.
+- `src/data/mappings/` — a **named import mapping**: the marketing tool's
+  CSV columns (`Full Name`, `Channel`, …) map onto `showcase_inquiry` once,
+  as governed metadata; every import then just passes
+  `mappingName: "showcase_inquiry_feed"` to
+  `POST /api/v1/data/showcase_inquiry/import` — re-importing the same file
+  is idempotent (artifact-declared upsert on email).
 
 ## Extensions & analytics
 

examples/app-showcase/test/gap-fill.test.ts

@@ -33,6 +33,33 @@ describe('showcase gap fill — analytics cube', () => {
   });
 });
 
+describe('showcase gap fill — named import mapping (#2611)', () => {
+  it('is wired into the stack definition', () => {
+    const mappings = (stack as { mappings?: Array<{ name: string }> }).mappings ?? [];
+    expect(mappings.map((m) => m.name)).toContain('showcase_inquiry_feed');
+  });
+
+  it('targets an existing object and its upsertKey fields exist on that object', () => {
+    const mappings = (stack as { mappings?: Array<{ targetObject: string; upsertKey?: string[]; fieldMapping: Array<{ target: string | string[] }> }> }).mappings ?? [];
+    const objects = ((stack as { objects?: Array<{ name: string; fields?: Record<string, unknown> }> }).objects ?? []);
+    for (const m of mappings) {
+      const target = objects.find((o) => o.name === m.targetObject);
+      expect(target, `mapping targets missing object '${m.targetObject}'`).toBeDefined();
+      const fieldNames = new Set(Object.keys(target?.fields ?? {}));
+      for (const key of m.upsertKey ?? []) {
+        expect(fieldNames.has(key), `upsertKey '${key}' not a field of '${m.targetObject}'`).toBe(true);
+      }
+      // Every mapped target lands on a real field — a typo'd target would
+      // silently import into nowhere.
+      for (const entry of m.fieldMapping) {
+        for (const t of Array.isArray(entry.target) ? entry.target : [entry.target]) {
+          expect(fieldNames.has(t), `mapped target '${t}' not a field of '${m.targetObject}'`).toBe(true);
+        }
+      }
+    }
+  });
+});
+
 describe('showcase gap fill — declarative api endpoints', () => {
   it('is wired into the stack definition', () => {
     const apis = (stack as { apis?: Array<{ name: string }> }).apis ?? [];

packages/metadata-core/src/types.ts

@@ -21,6 +21,7 @@ export const MetadataTypeSchema = z.enum([
   'field',
   'validation',
   'hook',
+  'mapping',
   'view',
   'page',
   'dashboard',

packages/rest/src/import-integration.test.ts

@@ -309,3 +309,110 @@ describe('import route — real engine + protocol integration', () => {
     expect(String(res._json.error)).toMatch(/xlsx/i);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Named mapping artifacts (#2611) — `mappingName` resolves a registered
+// `mapping` item and applies its fieldMapping pipeline before coercion.
+// ---------------------------------------------------------------------------
+describe('import route — named mapping artifact (#2611)', () => {
+  let route: any;
+  let engine: any;
+
+  const TASK_CSV_MAPPING = {
+    name: 'task_feed_import',
+    label: 'Task feed import',
+    sourceFormat: 'csv',
+    targetObject: 'task',
+    fieldMapping: [
+      { source: 'ID', target: 'id', transform: 'none' },
+      { source: 'Task Title', target: 'title', transform: 'none' },
+      // Source system codes → select LABELS; the built-in metaMap coercion
+      // then turns the label (高/低) into the storage code (high/low) —
+      // the artifact transform and the coercion pipeline COMPOSE.
+      { source: 'Prio', target: 'priority', transform: 'map', params: { valueMap: { P1: '高', P3: '低' } } },
+      { source: 'Assignee', target: 'owner', transform: 'lookup' },
+      { source: 'ignored_by_projection', target: 'score', transform: 'constant', params: { value: 5 } },
+    ],
+    mode: 'upsert',
+    upsertKey: ['id'],
+  };
+
+  beforeEach(async () => {
+    ({ route, engine } = await boot());
+    engine.registry.registerItem('mapping', TASK_CSV_MAPPING as any, 'name');
+    engine.registry.registerItem(
+      'mapping',
+      { ...TASK_CSV_MAPPING, name: 'user_only_mapping', targetObject: 'user' } as any,
+      'name',
+    );
+    engine.registry.registerItem(
+      'mapping',
+      {
+        name: 'task_js_mapping', targetObject: 'task', sourceFormat: 'csv',
+        fieldMapping: [{ source: 'x', target: 'title', transform: 'javascript' }],
+      } as any,
+      'name',
+    );
+    engine.registry.registerItem(
+      'mapping',
+      { ...TASK_CSV_MAPPING, name: 'task_json_mapping', sourceFormat: 'json' } as any,
+      'name',
+    );
+  });
+
+  it('applies rename + map + constant + lookup, strict projection, artifact upsert defaults', async () => {
+    const csv = [
+      'ID,Task Title,Prio,Assignee,Junk Column',
+      't1,迁移旧数据,P1,张三,DROP-ME',
+      't2,巡检,P3,李四,DROP-ME-TOO',
+    ].join('\n');
+    // No writeMode/matchFields in the request — the artifact's
+    // mode:'upsert' + upsertKey:['id'] apply as defaults.
+    const res = await call(route, { format: 'csv', csv, mappingName: 'task_feed_import' });
+    expect(res._json).toMatchObject({ total: 2, ok: 2 });
+
+    const one = await engine.findOne('task', { where: { id: 't1' } });
+    // map: P1→高, then coercion 高→high; lookup: 张三→u1 via metaMap;
+    // constant: score=5; strict projection: Junk Column never lands.
+    expect(one).toMatchObject({ title: '迁移旧数据', priority: 'high', owner: 'u1', score: 5 });
+    expect(one['Junk Column']).toBeUndefined();
+
+    // Re-import the same file → artifact upsert semantics update, not dupe.
+    const res2 = await call(route, { format: 'csv', csv, mappingName: 'task_feed_import' });
+    expect(res2._json.ok).toBe(2);
+    const all = await engine.find('task', { where: {} });
+    expect(all.filter((r: any) => r.id === 't1')).toHaveLength(1);
+  });
+
+  it('404s on an unknown mappingName', async () => {
+    const res = await call(route, { format: 'csv', csv: 'ID\nx', mappingName: 'nope' });
+    expect(res._status).toBe(404);
+    expect(res._json.code).toBe('MAPPING_NOT_FOUND');
+  });
+
+  it('400s when the mapping targets a different object', async () => {
+    const res = await call(route, { format: 'csv', csv: 'ID\nx', mappingName: 'user_only_mapping' });
+    expect(res._status).toBe(400);
+    expect(res._json.code).toBe('MAPPING_TARGET_MISMATCH');
+  });
+
+  it('400s when mappingName and an inline mapping are both provided', async () => {
+    const res = await call(route, {
+      format: 'csv', csv: 'ID\nx', mappingName: 'task_feed_import', mapping: { ID: 'id' },
+    });
+    expect(res._status).toBe(400);
+    expect(res._json.code).toBe('CONFLICTING_MAPPING');
+  });
+
+  it('400s on a javascript transform instead of silently skipping it', async () => {
+    const res = await call(route, { format: 'csv', csv: 'x\n1', mappingName: 'task_js_mapping' });
+    expect(res._status).toBe(400);
+    expect(res._json.code).toBe('UNSUPPORTED_TRANSFORM');
+  });
+
+  it('400s when the payload format contradicts the artifact sourceFormat', async () => {
+    const res = await call(route, { format: 'csv', csv: 'ID\nx', mappingName: 'task_json_mapping' });
+    expect(res._status).toBe(400);
+    expect(res._json.code).toBe('MAPPING_FORMAT_MISMATCH');
+  });
+});