dtcs 0.13.0

Reference implementation of the Data Transformation Contract Standard (DTCS)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# Node API

Package: [`@eddiethedean/dtcs`](https://github.com/eddiethedean/dtcs/tree/main/bindings/node) — thin wrapper over [`@eddiethedean/dtcs-wasm`](wasm.md).

**Maturity:** experimental / optional npm publish. Prefer pinning both packages to the same tools version.

## Install

```bash
npm install @eddiethedean/dtcs@0.13.0 @eddiethedean/dtcs-wasm@0.13.0
```

Requires **Node.js with ESM** (`"type": "module"`). The package auto-loads WASM via `initSync` on import.

If the package is not yet on npm for your version, build from the monorepo (`file:../wasm`) — see below.

## Exact exports

| Export | Kind | Notes |
|--------|------|-------|
| `parseDocument(content, format)` | function | WASM parse; `content` is string or bytes |
| `validateContract(contract)` | function | Validate COM → `{ diagnostics }` |
| `conformanceDeclare(profile?)` | function | Capability declaration |
| `specVersion()` | function | Returns `"3.0.0"` |
| `parse(content, format?)` | alias | Encodes string → `parseDocument` (default `"yaml"`) |
| `validate(contract)` | alias | → `validateContract` |
| `conformanceDeclareAll()` | alias | → `conformanceDeclare()` with no profile |
| `SPEC_VERSION` | string const | Same as `specVersion()` at load time |
| `conformanceRun` | throws | Not available — use Rust CLI / Python |

**3.0 surface limits:** parse / validate / `conformanceDeclare` only. No reference runtime, offline `conformanceRun`, or `export-portable`. Use `pip install dtcs` or the Rust `dtcs` CLI for those.

## Map vs plain object

serde-wasm may return nested **`Map`** values. Coerce before treating as plain JSON:

```javascript
function mapToPlain(value) {
  if (value instanceof Map) {
    return Object.fromEntries(
      [...value.entries()].map(([k, v]) => [k, mapToPlain(v)]),
    );
  }
  if (Array.isArray(value)) return value.map(mapToPlain);
  return value;
}
```

## Runnable example

```javascript
import {
  parse,
  validate,
  conformanceDeclareAll,
  SPEC_VERSION,
} from "@eddiethedean/dtcs";

function mapToPlain(value) {
  if (value instanceof Map) {
    return Object.fromEntries(
      [...value.entries()].map(([k, v]) => [k, mapToPlain(v)]),
    );
  }
  if (Array.isArray(value)) return value.map(mapToPlain);
  return value;
}

const yaml = `
dtcsVersion: "3.0.0"
id: "demo.minimal"
name: "Minimal Demo"
version: "0.1.0"
metadata:
  description: "node smoke"
  classification: internal
  governance: { owner: "docs", steward: "docs" }
  provenance: { author: "docs", createdAt: "2026-01-01T00:00:00Z" }
inputs:
  - id: "in"
    schema:
      fields:
        - { name: "v", type: "string", nullable: false }
outputs:
  - id: "out"
    schema:
      fields:
        - { name: "v", type: "string", nullable: false }
lineage:
  mappings:
    - { output: "out", inputs: ["in"] }
`;

const parsed = mapToPlain(parse(yaml, "yaml"));
const report = validate(parsed.contract);
const ok = !report.diagnostics.some((d) => d.severity === "error");
console.log(SPEC_VERSION, ok, conformanceDeclareAll().primaryProfile);
```
## Errors

Validation failures are diagnostics, not thrown errors for ordinary invalid contracts. See [error-taxonomy.md](../user/error-taxonomy.md).

## Develop from the monorepo

```bash
cd bindings/wasm && npm run build
cd ../node && npm install --no-save file:../wasm && npm test
```

## See also

- [wasm.md](wasm.md) · [python.md](python.md) · [rust.md](rust.md)
- Package README: [bindings/node/README.md](https://github.com/eddiethedean/dtcs/blob/main/bindings/node/README.md)