@contractspec/lib.data-exchange-core

Website: https://contractspec.io

SchemaModel-first core primitives for data import, export, mapping, preview, and reconciliation planning.

What It Provides

• Headless CSV, JSON, and XML codecs.
• Normalized RecordBatch contracts for runtime data interchange.
• SchemaModel mapping inference, coercion, and validation helpers.
• Import/export planning and preview diff APIs.

Installation

npm install @contractspec/lib.data-exchange-core

or

bun add @contractspec/lib.data-exchange-core

Usage

Import the root entrypoint from @contractspec/lib.data-exchange-core, or use subpaths such as ./codecs, ./mapping, ./plans, ./preview, ./records, ./schema, and ./types.

Import Templates

Developers can define the recommended import shape once, then let users upload files with different column labels or value formats:

import {
	createImportPlan,
	createRecordBatch,
	defineDataExchangeTemplate,
	previewImport,
} from "@contractspec/lib.data-exchange-core";

const template = defineDataExchangeTemplate({
	key: "accounts.import",
	version: "1.0.0",
	columns: [
		{
			key: "id",
			label: "Account ID",
			targetField: "id",
			required: true,
			sourceAliases: ["Account Identifier", "External ID"],
		},
		{
			key: "amount",
			label: "Amount",
			targetField: "amount",
			format: {
				kind: "number",
				decimalSeparator: ",",
				thousandsSeparator: ".",
			},
		},
	],
});

const sourceBatch = createRecordBatch([
	{ "Account Identifier": "acc-1", Amount: "1.234,50" },
]);

const preview = previewImport(
	createImportPlan({
		source: { kind: "memory", batch: sourceBatch, format: "csv" },
		target: { kind: "memory", format: "json" },
		schema: AccountImportSchema,
		sourceBatch,
		template,
	})
);

Template resolution uses exact headers, aliases, normalized labels, and SchemaModel fallback inference. Explicit mappings still override template mappings. defineImportTemplate remains available as a backwards-compatible import-specific alias.