@intellectual-frontiers/integrations 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/governance/exchange.d.ts +224 -0
- package/dist/governance/exchange.js +86 -0
- package/dist/governance/ids.d.ts +61 -0
- package/dist/governance/ids.js +53 -0
- package/dist/governance/mod.d.ts +11 -0
- package/dist/governance/mod.js +12 -0
- package/dist/governance/observe.d.ts +172 -0
- package/dist/governance/observe.js +139 -0
- package/dist/logical/conformance.d.ts +44 -0
- package/dist/logical/conformance.js +108 -0
- package/dist/logical/constraints.d.ts +86 -0
- package/dist/logical/constraints.js +112 -0
- package/dist/logical/exchange.d.ts +98 -0
- package/dist/logical/exchange.js +135 -0
- package/dist/logical/ledger.d.ts +94 -0
- package/dist/logical/ledger.js +90 -0
- package/dist/logical/mapping.d.ts +64 -0
- package/dist/logical/mapping.js +99 -0
- package/dist/logical/mod.d.ts +18 -0
- package/dist/logical/mod.js +19 -0
- package/dist/logical/observe.d.ts +222 -0
- package/dist/logical/observe.js +156 -0
- package/dist/logical/plugin.d.ts +91 -0
- package/dist/logical/plugin.js +53 -0
- package/dist/logical/ports.d.ts +102 -0
- package/dist/logical/ports.js +31 -0
- package/dist/logical/registry.d.ts +72 -0
- package/dist/logical/registry.js +81 -0
- package/dist/logical/tree.d.ts +91 -0
- package/dist/logical/tree.js +114 -0
- package/dist/mod.d.ts +15 -0
- package/dist/mod.js +16 -0
- package/dist/physical/http/mod.d.ts +54 -0
- package/dist/physical/http/mod.js +114 -0
- package/dist/physical/transport/mod.d.ts +79 -0
- package/dist/physical/transport/mod.js +61 -0
- package/dist/surfaces/headless/mod.d.ts +46 -0
- package/dist/surfaces/headless/mod.js +258 -0
- package/package.json +67 -4
- package/src/governance/exchange.ts +220 -0
- package/src/governance/ids.ts +92 -0
- package/src/governance/mod.ts +12 -0
- package/src/governance/observe.ts +226 -0
- package/src/logical/conformance.ts +113 -0
- package/src/logical/constraints.ts +154 -0
- package/src/logical/exchange.ts +184 -0
- package/src/logical/ledger.ts +123 -0
- package/src/logical/mapping.ts +114 -0
- package/src/logical/mod.ts +19 -0
- package/src/logical/observe.ts +314 -0
- package/src/logical/plugin.ts +102 -0
- package/src/logical/ports.ts +89 -0
- package/src/logical/registry.ts +93 -0
- package/src/logical/tree.ts +153 -0
- package/src/mod.ts +16 -0
- package/src/physical/http/mod.ts +134 -0
- package/src/physical/transport/mod.ts +85 -0
- package/src/surfaces/headless/mod.ts +293 -0
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
// Spec: 0006-integrations-exchange FR-010, FR-011, FR-012
|
|
2
|
+
/**
|
|
3
|
+
* Acknowledgements, outcomes and the exchange state machine (commons integrations 0006-integrations-exchange): the typed acknowledgements of the standards
|
|
4
|
+
* (X12 TA1 and 999, HL7 ACK, FHIR OperationOutcome) reduced to one status, and the life of a message as a total transition function of a state and an event.
|
|
5
|
+
*
|
|
6
|
+
* @module
|
|
7
|
+
*/
|
|
8
|
+
import { absurd, err, ok } from "@intellectual-frontiers/core";
|
|
9
|
+
/** What an acknowledgement comes to. */
|
|
10
|
+
export function statusOf(a) {
|
|
11
|
+
switch (a.kind) {
|
|
12
|
+
case "x12-ta1":
|
|
13
|
+
case "x12-999":
|
|
14
|
+
return a.status;
|
|
15
|
+
case "hl7-ack":
|
|
16
|
+
switch (a.code) {
|
|
17
|
+
case "AA":
|
|
18
|
+
case "CA":
|
|
19
|
+
return "accepted";
|
|
20
|
+
case "AE":
|
|
21
|
+
case "CE":
|
|
22
|
+
return "accepted-with-errors";
|
|
23
|
+
case "AR":
|
|
24
|
+
case "CR":
|
|
25
|
+
return "rejected";
|
|
26
|
+
default:
|
|
27
|
+
return absurd(a.code);
|
|
28
|
+
}
|
|
29
|
+
case "fhir-operation-outcome":
|
|
30
|
+
return a.issues.some((i) => i.severity === "error") ? "rejected" : a.issues.some((i) => i.severity === "warning") ? "accepted-with-errors" : "accepted";
|
|
31
|
+
default:
|
|
32
|
+
return absurd(a);
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
const ACK_KIND_TABLE = { "x12-ta1": true, "x12-999": true, "hl7-ack": true, "fhir-operation-outcome": true };
|
|
36
|
+
/** Every kind of acknowledgement, as a closed list of strings a consumer may carry as data. */
|
|
37
|
+
export const ACK_KINDS = Object.keys(ACK_KIND_TABLE).filter((k) => Object.hasOwn(ACK_KIND_TABLE, k));
|
|
38
|
+
/** Every acknowledgement status. */
|
|
39
|
+
export const ACK_STATUSES = ["accepted", "accepted-with-errors", "rejected"];
|
|
40
|
+
/** Every reason a message is rejected: the partner said no (`nack`), or it was invalid on receipt (`invalid`). */
|
|
41
|
+
export const REJECTION_KINDS = ["nack", "invalid"];
|
|
42
|
+
const illegal = (from, event) => err({ kind: "illegal", from: from.kind, event: event.kind });
|
|
43
|
+
function acked(status) {
|
|
44
|
+
switch (status) {
|
|
45
|
+
case "accepted":
|
|
46
|
+
case "accepted-with-errors":
|
|
47
|
+
return { kind: "acknowledged", status };
|
|
48
|
+
case "rejected":
|
|
49
|
+
return { kind: "rejected", reason: "nack" };
|
|
50
|
+
default:
|
|
51
|
+
return absurd(status);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
/** The next state: total over every state and every event, an illegal pair giving an error and never throwing. */
|
|
55
|
+
export function transition(state, event, policy) {
|
|
56
|
+
switch (state.kind) {
|
|
57
|
+
case "pending":
|
|
58
|
+
switch (event.kind) {
|
|
59
|
+
case "send":
|
|
60
|
+
return ok({ kind: "sent", attempt: 1, at: event.at });
|
|
61
|
+
case "receive":
|
|
62
|
+
return ok({ kind: "received", at: event.at });
|
|
63
|
+
case "ack":
|
|
64
|
+
case "timeout":
|
|
65
|
+
case "retry":
|
|
66
|
+
case "invalid":
|
|
67
|
+
return illegal(state, event);
|
|
68
|
+
default:
|
|
69
|
+
return absurd(event);
|
|
70
|
+
}
|
|
71
|
+
case "sent":
|
|
72
|
+
switch (event.kind) {
|
|
73
|
+
case "ack":
|
|
74
|
+
return ok(acked(event.status));
|
|
75
|
+
case "timeout":
|
|
76
|
+
return ok(state.attempt < policy.maxAttempts ? { kind: "retrying", attempt: state.attempt } : { kind: "abandoned", attempts: state.attempt });
|
|
77
|
+
case "send":
|
|
78
|
+
case "receive":
|
|
79
|
+
case "retry":
|
|
80
|
+
case "invalid":
|
|
81
|
+
return illegal(state, event);
|
|
82
|
+
default:
|
|
83
|
+
return absurd(event);
|
|
84
|
+
}
|
|
85
|
+
case "retrying":
|
|
86
|
+
switch (event.kind) {
|
|
87
|
+
case "retry":
|
|
88
|
+
return ok({ kind: "sent", attempt: state.attempt + 1, at: event.at });
|
|
89
|
+
case "send":
|
|
90
|
+
case "receive":
|
|
91
|
+
case "ack":
|
|
92
|
+
case "timeout":
|
|
93
|
+
case "invalid":
|
|
94
|
+
return illegal(state, event);
|
|
95
|
+
default:
|
|
96
|
+
return absurd(event);
|
|
97
|
+
}
|
|
98
|
+
case "received":
|
|
99
|
+
switch (event.kind) {
|
|
100
|
+
case "ack":
|
|
101
|
+
return ok(acked(event.status));
|
|
102
|
+
case "invalid":
|
|
103
|
+
return ok({ kind: "rejected", reason: "invalid" });
|
|
104
|
+
case "send":
|
|
105
|
+
case "receive":
|
|
106
|
+
case "timeout":
|
|
107
|
+
case "retry":
|
|
108
|
+
return illegal(state, event);
|
|
109
|
+
default:
|
|
110
|
+
return absurd(event);
|
|
111
|
+
}
|
|
112
|
+
case "acknowledged":
|
|
113
|
+
case "rejected":
|
|
114
|
+
case "abandoned":
|
|
115
|
+
return illegal(state, event);
|
|
116
|
+
default:
|
|
117
|
+
return absurd(state);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
/** Whether a state is final: nothing follows it. */
|
|
121
|
+
export function isFinal(s) {
|
|
122
|
+
switch (s.kind) {
|
|
123
|
+
case "acknowledged":
|
|
124
|
+
case "rejected":
|
|
125
|
+
case "abandoned":
|
|
126
|
+
return true;
|
|
127
|
+
case "pending":
|
|
128
|
+
case "sent":
|
|
129
|
+
case "received":
|
|
130
|
+
case "retrying":
|
|
131
|
+
return false;
|
|
132
|
+
default:
|
|
133
|
+
return absurd(s);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ledger port of exchange (commons integrations 0006-integrations-exchange): a typed record of functions, each returning a `Result`, with which a consumer keeps the trail of a
|
|
3
|
+
* load without the library knowing where it is kept (a database, a file, memory). It appends stage events, checks the intake of a content by its hash, and records the outcome of a
|
|
4
|
+
* validation or an acknowledgement by code. A stage is an opaque branded text: the consumer's code list of stages lives with the consumer, not here. An event never carries a payload
|
|
5
|
+
* value: its fields are identifiers, a code, an instant and a digest, each made by a smart constructor that admits no free text.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { type Brand, type Result } from "@intellectual-frontiers/core";
|
|
10
|
+
import { type IdError, type Instant, type Sha256 } from "@intellectual-frontiers/integrations/governance";
|
|
11
|
+
/** The identity of one load, as the consumer names it. */
|
|
12
|
+
export type LoadId = Brand<string, "LoadId">;
|
|
13
|
+
/** A stage of the consumer's pipeline, an opaque code such as `RECEIVED` or `VALIDATED`. */
|
|
14
|
+
export type Stage = Brand<string, "Stage">;
|
|
15
|
+
/** A code that says why, or what came of a check: lower-case words joined by dashes. */
|
|
16
|
+
export type OutcomeCode = Brand<string, "OutcomeCode">;
|
|
17
|
+
/** The key that names the same item across loads (a message id, a control number): what two contents of one item share. */
|
|
18
|
+
export type ItemKey = Brand<string, "ItemKey">;
|
|
19
|
+
/** A load id: letters, digits and `. _ : -`, up to 128. Free text is refused, and the refusal does not repeat it. */
|
|
20
|
+
export declare const parseLoadId: (t: string) => Result<LoadId, IdError>;
|
|
21
|
+
/** A stage: upper-case words joined by underscores. */
|
|
22
|
+
export declare const parseStage: (t: string) => Result<Stage, IdError>;
|
|
23
|
+
/** An outcome or reason code. */
|
|
24
|
+
export declare const parseOutcomeCode: (t: string) => Result<OutcomeCode, IdError>;
|
|
25
|
+
/** An item key. */
|
|
26
|
+
export declare const parseItemKey: (t: string) => Result<ItemKey, IdError>;
|
|
27
|
+
/** One event of a load: a stage reached, with a reason code and a digest where there are any. Never a payload value. */
|
|
28
|
+
export type LedgerEvent = {
|
|
29
|
+
readonly loadId: LoadId;
|
|
30
|
+
readonly stage: Stage;
|
|
31
|
+
readonly reasonCode?: OutcomeCode;
|
|
32
|
+
readonly at: Instant;
|
|
33
|
+
readonly contentHash?: Sha256;
|
|
34
|
+
};
|
|
35
|
+
/** What a content is, on intake. */
|
|
36
|
+
export type IntakeRequest = {
|
|
37
|
+
readonly loadId: LoadId;
|
|
38
|
+
readonly itemKey: ItemKey;
|
|
39
|
+
readonly contentHash: Sha256;
|
|
40
|
+
readonly at: Instant;
|
|
41
|
+
};
|
|
42
|
+
/** What the ledger says of a content on intake: never seen; the same content seen before (in the load named); or another content of the same item (in the load named). */
|
|
43
|
+
export type Intake = {
|
|
44
|
+
readonly kind: "first-seen";
|
|
45
|
+
} | {
|
|
46
|
+
readonly kind: "duplicate";
|
|
47
|
+
readonly of: LoadId;
|
|
48
|
+
} | {
|
|
49
|
+
readonly kind: "conflict";
|
|
50
|
+
readonly with: LoadId;
|
|
51
|
+
};
|
|
52
|
+
/** Which check an outcome is of. */
|
|
53
|
+
export type OutcomeKind = "validation" | "acknowledgement";
|
|
54
|
+
/** The outcome of a check, by code. */
|
|
55
|
+
export type OutcomeRecord = {
|
|
56
|
+
readonly loadId: LoadId;
|
|
57
|
+
readonly kind: OutcomeKind;
|
|
58
|
+
readonly code: OutcomeCode;
|
|
59
|
+
readonly at: Instant;
|
|
60
|
+
};
|
|
61
|
+
/** Why the ledger could not answer. */
|
|
62
|
+
export type LedgerError = {
|
|
63
|
+
readonly kind: "unavailable";
|
|
64
|
+
} | {
|
|
65
|
+
readonly kind: "unknown-load";
|
|
66
|
+
readonly loadId: LoadId;
|
|
67
|
+
};
|
|
68
|
+
/** The ledger port. */
|
|
69
|
+
export type LedgerPort = {
|
|
70
|
+
readonly append: (event: LedgerEvent) => Promise<Result<void, LedgerError>>;
|
|
71
|
+
readonly intake: (request: IntakeRequest) => Promise<Result<Intake, LedgerError>>;
|
|
72
|
+
readonly outcome: (record: OutcomeRecord) => Promise<Result<void, LedgerError>>;
|
|
73
|
+
readonly events: (loadId: LoadId) => Promise<Result<readonly LedgerEvent[], LedgerError>>;
|
|
74
|
+
readonly outcomes: (loadId: LoadId) => Promise<Result<readonly OutcomeRecord[], LedgerError>>;
|
|
75
|
+
};
|
|
76
|
+
/** A ledger in memory. */
|
|
77
|
+
export declare function memoryLedger(): LedgerPort;
|
|
78
|
+
/** What a ledger conformance finds wrong. */
|
|
79
|
+
export type LedgerFinding = {
|
|
80
|
+
readonly rule: string;
|
|
81
|
+
readonly message: string;
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* The conformance suite of a ledger: `make` gives a fresh, empty ledger each time. It finds a ledger that does not keep events in the order appended, that does not tell first-seen from
|
|
85
|
+
* duplicate from conflict, that accepts an outcome for a load it has no event of, or that does not keep outcomes. Any implementation (memory, a database) runs it.
|
|
86
|
+
*/
|
|
87
|
+
export declare function conformLedger(make: () => LedgerPort, ids: {
|
|
88
|
+
readonly load: (n: number) => LoadId;
|
|
89
|
+
readonly stage: (name: string) => Stage;
|
|
90
|
+
readonly code: (name: string) => OutcomeCode;
|
|
91
|
+
readonly key: (n: number) => ItemKey;
|
|
92
|
+
readonly hash: (n: number) => Sha256;
|
|
93
|
+
readonly at: Instant;
|
|
94
|
+
}): Promise<readonly LedgerFinding[]>;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
// Spec: 0006-integrations-exchange FR-013, FR-014, FR-015
|
|
2
|
+
/**
|
|
3
|
+
* The ledger port of exchange (commons integrations 0006-integrations-exchange): a typed record of functions, each returning a `Result`, with which a consumer keeps the trail of a
|
|
4
|
+
* load without the library knowing where it is kept (a database, a file, memory). It appends stage events, checks the intake of a content by its hash, and records the outcome of a
|
|
5
|
+
* validation or an acknowledgement by code. A stage is an opaque branded text: the consumer's code list of stages lives with the consumer, not here. An event never carries a payload
|
|
6
|
+
* value: its fields are identifiers, a code, an instant and a digest, each made by a smart constructor that admits no free text.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
import { err, ok } from "@intellectual-frontiers/core";
|
|
11
|
+
import { brand } from "@intellectual-frontiers/integrations/governance";
|
|
12
|
+
const make = (what, pattern, expected, text) => (pattern.test(text) ? ok(brand(text)) : err({ kind: "id", what, expected }));
|
|
13
|
+
/** A load id: letters, digits and `. _ : -`, up to 128. Free text is refused, and the refusal does not repeat it. */
|
|
14
|
+
export const parseLoadId = (t) => make("LoadId", /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/, "letters, digits and . _ : -, up to 128", t);
|
|
15
|
+
/** A stage: upper-case words joined by underscores. */
|
|
16
|
+
export const parseStage = (t) => make("Stage", /^[A-Z][A-Z0-9_]{1,31}$/, "upper-case words joined by underscores", t);
|
|
17
|
+
/** An outcome or reason code. */
|
|
18
|
+
export const parseOutcomeCode = (t) => make("OutcomeCode", /^[a-z0-9][a-z0-9-]{0,63}$/, "lower-case words joined by dashes", t);
|
|
19
|
+
/** An item key. */
|
|
20
|
+
export const parseItemKey = (t) => make("ItemKey", /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/, "letters, digits and . _ : -, up to 128", t);
|
|
21
|
+
/** A ledger in memory. */
|
|
22
|
+
export function memoryLedger() {
|
|
23
|
+
const events = new Map();
|
|
24
|
+
const outcomes = new Map();
|
|
25
|
+
const byHash = new Map();
|
|
26
|
+
const byItem = new Map();
|
|
27
|
+
return {
|
|
28
|
+
append: (e) => {
|
|
29
|
+
events.set(e.loadId, [...(events.get(e.loadId) ?? []), e]);
|
|
30
|
+
return Promise.resolve(ok(undefined));
|
|
31
|
+
},
|
|
32
|
+
intake: (r) => {
|
|
33
|
+
const same = byHash.get(r.contentHash);
|
|
34
|
+
if (same !== undefined)
|
|
35
|
+
return Promise.resolve(ok({ kind: "duplicate", of: same }));
|
|
36
|
+
const item = byItem.get(r.itemKey);
|
|
37
|
+
if (item !== undefined)
|
|
38
|
+
return Promise.resolve(ok({ kind: "conflict", with: item.loadId }));
|
|
39
|
+
byHash.set(r.contentHash, r.loadId);
|
|
40
|
+
byItem.set(r.itemKey, { hash: r.contentHash, loadId: r.loadId });
|
|
41
|
+
return Promise.resolve(ok({ kind: "first-seen" }));
|
|
42
|
+
},
|
|
43
|
+
outcome: (o) => {
|
|
44
|
+
if (!events.has(o.loadId))
|
|
45
|
+
return Promise.resolve(err({ kind: "unknown-load", loadId: o.loadId }));
|
|
46
|
+
outcomes.set(o.loadId, [...(outcomes.get(o.loadId) ?? []), o]);
|
|
47
|
+
return Promise.resolve(ok(undefined));
|
|
48
|
+
},
|
|
49
|
+
events: (id) => Promise.resolve(ok(events.get(id) ?? [])),
|
|
50
|
+
outcomes: (id) => Promise.resolve(events.has(id) ? ok(outcomes.get(id) ?? []) : err({ kind: "unknown-load", loadId: id })),
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The conformance suite of a ledger: `make` gives a fresh, empty ledger each time. It finds a ledger that does not keep events in the order appended, that does not tell first-seen from
|
|
55
|
+
* duplicate from conflict, that accepts an outcome for a load it has no event of, or that does not keep outcomes. Any implementation (memory, a database) runs it.
|
|
56
|
+
*/
|
|
57
|
+
export async function conformLedger(make, ids) {
|
|
58
|
+
const out = [];
|
|
59
|
+
const bad = (rule, message) => void out.push({ rule, message });
|
|
60
|
+
const l = make();
|
|
61
|
+
const a = ids.load(1);
|
|
62
|
+
const b = ids.load(2);
|
|
63
|
+
const c = ids.load(3);
|
|
64
|
+
await l.append({ loadId: a, stage: ids.stage("RECEIVED"), at: ids.at });
|
|
65
|
+
await l.append({ loadId: a, stage: ids.stage("PARSED"), reasonCode: ids.code("ok"), at: ids.at, contentHash: ids.hash(1) });
|
|
66
|
+
const evs = await l.events(a);
|
|
67
|
+
if (evs.kind !== "ok" || evs.value.map((e) => e.stage).join(",") !== "RECEIVED,PARSED")
|
|
68
|
+
bad("ledger/order", "events are not kept in the order appended");
|
|
69
|
+
const first = await l.intake({ loadId: a, itemKey: ids.key(1), contentHash: ids.hash(1), at: ids.at });
|
|
70
|
+
if (first.kind !== "ok" || first.value.kind !== "first-seen")
|
|
71
|
+
bad("ledger/first-seen", "a content never seen is not first-seen");
|
|
72
|
+
const dup = await l.intake({ loadId: b, itemKey: ids.key(2), contentHash: ids.hash(1), at: ids.at });
|
|
73
|
+
if (dup.kind !== "ok" || dup.value.kind !== "duplicate" || dup.value.of !== a)
|
|
74
|
+
bad("ledger/duplicate", "the same content is not a duplicate of the load that had it");
|
|
75
|
+
const conflict = await l.intake({ loadId: c, itemKey: ids.key(1), contentHash: ids.hash(3), at: ids.at });
|
|
76
|
+
if (conflict.kind !== "ok" || conflict.value.kind !== "conflict" || conflict.value.with !== a)
|
|
77
|
+
bad("ledger/conflict", "another content of the same item is not a conflict");
|
|
78
|
+
const unknown = await l.outcome({ loadId: ids.load(99), kind: "validation", code: ids.code("none"), at: ids.at });
|
|
79
|
+
if (unknown.kind !== "err" || unknown.error.kind !== "unknown-load")
|
|
80
|
+
bad("ledger/unknown-load", "an outcome for a load with no event is accepted");
|
|
81
|
+
await l.outcome({ loadId: a, kind: "validation", code: ids.code("cardinality-min"), at: ids.at });
|
|
82
|
+
const os = await l.outcomes(a);
|
|
83
|
+
if (os.kind !== "ok" || os.value.length !== 1 || os.value[0]?.code !== "cardinality-min")
|
|
84
|
+
bad("ledger/outcomes", "an outcome recorded is not read back");
|
|
85
|
+
const other = make();
|
|
86
|
+
const fresh = await other.intake({ loadId: a, itemKey: ids.key(1), contentHash: ids.hash(1), at: ids.at });
|
|
87
|
+
if (fresh.kind !== "ok" || fresh.value.kind !== "first-seen")
|
|
88
|
+
bad("ledger/fresh", "a fresh ledger remembers another's contents");
|
|
89
|
+
return out;
|
|
90
|
+
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Mappings between standards, declared as data (commons integrations 0006-integrations-exchange): from a standard to a canonical shape or to another standard,
|
|
3
|
+
* such as an X12 837 to a FHIR Claim. Each field of the source ends in exactly one of three states (Kanon rule 5): mapped, carried (kept as it is in a named place)
|
|
4
|
+
* or dropped by name with its reason. A field that ends in none is a finding, and so is a mapping that drops anything, because a lossy mapping is a finding.
|
|
5
|
+
*
|
|
6
|
+
* @module
|
|
7
|
+
*/
|
|
8
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
9
|
+
import type { Ref } from "@intellectual-frontiers/integrations/governance";
|
|
10
|
+
import { type Finding } from "./constraints.js";
|
|
11
|
+
import { pathsOf, type Transaction } from "./tree.js";
|
|
12
|
+
/** How a value changes on its way. */
|
|
13
|
+
export type Transform = {
|
|
14
|
+
readonly kind: "identity";
|
|
15
|
+
} | {
|
|
16
|
+
readonly kind: "upper";
|
|
17
|
+
} | {
|
|
18
|
+
readonly kind: "lower";
|
|
19
|
+
} | {
|
|
20
|
+
readonly kind: "trim";
|
|
21
|
+
} | {
|
|
22
|
+
readonly kind: "table";
|
|
23
|
+
readonly table: Readonly<Record<string, string>>;
|
|
24
|
+
readonly otherwise: "keep" | "drop";
|
|
25
|
+
};
|
|
26
|
+
/** What a mapping does with one field, or a subtree, of the source (a path stands for everything below it). */
|
|
27
|
+
export type MapRule = {
|
|
28
|
+
readonly kind: "map";
|
|
29
|
+
readonly from: string;
|
|
30
|
+
readonly to: string;
|
|
31
|
+
readonly transform: Transform;
|
|
32
|
+
} | {
|
|
33
|
+
readonly kind: "carry";
|
|
34
|
+
readonly from: string;
|
|
35
|
+
readonly to: string;
|
|
36
|
+
} | {
|
|
37
|
+
readonly kind: "drop";
|
|
38
|
+
readonly from: string;
|
|
39
|
+
readonly reason: string;
|
|
40
|
+
};
|
|
41
|
+
/** A mapping between two schemas. */
|
|
42
|
+
export type Mapping = {
|
|
43
|
+
readonly id: string;
|
|
44
|
+
readonly source: Ref<"schema">;
|
|
45
|
+
readonly target: Ref<"schema">;
|
|
46
|
+
readonly sourceTransaction: string;
|
|
47
|
+
readonly targetTransaction: string;
|
|
48
|
+
readonly rules: readonly MapRule[];
|
|
49
|
+
};
|
|
50
|
+
/** A value through a transform; `undefined` where a table drops it. */
|
|
51
|
+
export declare function applyTransform(t: Transform, value: string): string | undefined;
|
|
52
|
+
/** The rule that says what becomes of a path: the most specific one. */
|
|
53
|
+
export declare function ruleFor(m: Mapping, path: string): MapRule | undefined;
|
|
54
|
+
/** The findings of a mapping against the paths of its source (the value-bearing ones): a path that ends in no rule, a rule on no path, a target written by two rules, and a drop. */
|
|
55
|
+
export declare function coverage(m: Mapping, sourcePaths: readonly string[]): readonly Finding[];
|
|
56
|
+
/** The value-bearing paths of a transaction, each once. */
|
|
57
|
+
export declare function valuePaths(t: Transaction): readonly string[];
|
|
58
|
+
/** Every path a transaction has: for a schema's own list of paths. */
|
|
59
|
+
export declare const allPaths: typeof pathsOf;
|
|
60
|
+
/**
|
|
61
|
+
* A source transaction translated by a mapping into a flat transaction of the target: one segment for each value, its id the path below the target's root. A value of a
|
|
62
|
+
* field that is dropped is not written; a value whose path has no rule stops the translation with `unmapped-source-field`, so that nothing is lost silently.
|
|
63
|
+
*/
|
|
64
|
+
export declare function translate(m: Mapping, source: Transaction): Result<Transaction, readonly Finding[]>;
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
// Spec: 0006-integrations-exchange FR-008, FR-009
|
|
2
|
+
/**
|
|
3
|
+
* Mappings between standards, declared as data (commons integrations 0006-integrations-exchange): from a standard to a canonical shape or to another standard,
|
|
4
|
+
* such as an X12 837 to a FHIR Claim. Each field of the source ends in exactly one of three states (Kanon rule 5): mapped, carried (kept as it is in a named place)
|
|
5
|
+
* or dropped by name with its reason. A field that ends in none is a finding, and so is a mapping that drops anything, because a lossy mapping is a finding.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { absurd, err, ok } from "@intellectual-frontiers/core";
|
|
10
|
+
import { finding } from "./constraints.js";
|
|
11
|
+
import { element, entries, pathsOf, segment } from "./tree.js";
|
|
12
|
+
/** A value through a transform; `undefined` where a table drops it. */
|
|
13
|
+
export function applyTransform(t, value) {
|
|
14
|
+
switch (t.kind) {
|
|
15
|
+
case "identity":
|
|
16
|
+
return value;
|
|
17
|
+
case "upper":
|
|
18
|
+
return value.toUpperCase();
|
|
19
|
+
case "lower":
|
|
20
|
+
return value.toLowerCase();
|
|
21
|
+
case "trim":
|
|
22
|
+
return value.trim();
|
|
23
|
+
case "table":
|
|
24
|
+
return Object.hasOwn(t.table, value) ? t.table[value] : t.otherwise === "keep" ? value : undefined;
|
|
25
|
+
default:
|
|
26
|
+
return absurd(t);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
const covers = (from, path) => path === from || path.startsWith(`${from}.`);
|
|
30
|
+
/** The rule that says what becomes of a path: the most specific one. */
|
|
31
|
+
export function ruleFor(m, path) {
|
|
32
|
+
let best;
|
|
33
|
+
for (const r of m.rules)
|
|
34
|
+
if (covers(r.from, path) && (best === undefined || r.from.length > best.from.length))
|
|
35
|
+
best = r;
|
|
36
|
+
return best;
|
|
37
|
+
}
|
|
38
|
+
/** The findings of a mapping against the paths of its source (the value-bearing ones): a path that ends in no rule, a rule on no path, a target written by two rules, and a drop. */
|
|
39
|
+
export function coverage(m, sourcePaths) {
|
|
40
|
+
const out = [];
|
|
41
|
+
for (const p of sourcePaths)
|
|
42
|
+
if (ruleFor(m, p) === undefined)
|
|
43
|
+
out.push(finding("schema", "error", "unmapped-source-field", p, "no rule maps, carries or drops it"));
|
|
44
|
+
for (const r of m.rules) {
|
|
45
|
+
if (!sourcePaths.some((p) => covers(r.from, p)))
|
|
46
|
+
out.push(finding("schema", "warning", "unknown-path", r.from, "a rule of the mapping names no field of the source"));
|
|
47
|
+
if (r.kind === "drop")
|
|
48
|
+
out.push(finding("schema", "warning", "lossy-mapping", r.from, `dropped: ${r.reason}`));
|
|
49
|
+
}
|
|
50
|
+
const targets = new Map();
|
|
51
|
+
for (const r of m.rules) {
|
|
52
|
+
if (r.kind === "drop")
|
|
53
|
+
continue;
|
|
54
|
+
const before = targets.get(r.to);
|
|
55
|
+
if (before !== undefined && before !== r.from)
|
|
56
|
+
out.push(finding("schema", "error", "mapping-target-conflict", r.to, "two sources are written to it"));
|
|
57
|
+
targets.set(r.to, r.from);
|
|
58
|
+
}
|
|
59
|
+
return out;
|
|
60
|
+
}
|
|
61
|
+
/** The value-bearing paths of a transaction, each once. */
|
|
62
|
+
export function valuePaths(t) {
|
|
63
|
+
return [...new Set(entries(t).map((e) => e.path))];
|
|
64
|
+
}
|
|
65
|
+
/** Every path a transaction has: for a schema's own list of paths. */
|
|
66
|
+
export const allPaths = pathsOf;
|
|
67
|
+
/**
|
|
68
|
+
* A source transaction translated by a mapping into a flat transaction of the target: one segment for each value, its id the path below the target's root. A value of a
|
|
69
|
+
* field that is dropped is not written; a value whose path has no rule stops the translation with `unmapped-source-field`, so that nothing is lost silently.
|
|
70
|
+
*/
|
|
71
|
+
export function translate(m, source) {
|
|
72
|
+
if (source.id !== m.sourceTransaction)
|
|
73
|
+
return err([finding("schema", "error", "unknown-path", source.id, "the transaction is not the mapping's source")]);
|
|
74
|
+
const findings = [];
|
|
75
|
+
const children = [];
|
|
76
|
+
for (const e of entries(source)) {
|
|
77
|
+
const r = ruleFor(m, e.path);
|
|
78
|
+
if (r === undefined) {
|
|
79
|
+
findings.push(finding("schema", "error", "unmapped-source-field", e.at));
|
|
80
|
+
continue;
|
|
81
|
+
}
|
|
82
|
+
switch (r.kind) {
|
|
83
|
+
case "drop":
|
|
84
|
+
break;
|
|
85
|
+
case "map":
|
|
86
|
+
case "carry": {
|
|
87
|
+
const v = r.kind === "map" ? applyTransform(r.transform, e.value) : e.value;
|
|
88
|
+
if (v === undefined)
|
|
89
|
+
break;
|
|
90
|
+
const target = r.to + e.path.slice(r.from.length);
|
|
91
|
+
children.push(segment(target.startsWith(`${m.targetTransaction}.`) ? target.slice(m.targetTransaction.length + 1) : target, element("", v)));
|
|
92
|
+
break;
|
|
93
|
+
}
|
|
94
|
+
default:
|
|
95
|
+
return absurd(r);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
return findings.length > 0 ? err(findings) : ok({ kind: "transaction", id: m.targetTransaction, control: source.control, children });
|
|
99
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Layer 2 of Integrations, the logical layer (commons integrations 0003-integrations-logical): ports as typed records of functions; the observation, its entities
|
|
3
|
+
* and the `Connector` contract with the registry that pins connectors; the abstract tree, schema and profile as constraints, validation with findings at every level, mappings as
|
|
4
|
+
* data that account for every field, acknowledgements and the exchange state machine; the plugin contract of standards; and the conformance suites. Pure: it imports Core
|
|
5
|
+
* and governance and does no effect.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
export * from "./conformance.js";
|
|
10
|
+
export * from "./constraints.js";
|
|
11
|
+
export * from "./exchange.js";
|
|
12
|
+
export * from "./ledger.js";
|
|
13
|
+
export * from "./mapping.js";
|
|
14
|
+
export * from "./observe.js";
|
|
15
|
+
export * from "./plugin.js";
|
|
16
|
+
export * from "./ports.js";
|
|
17
|
+
export * from "./registry.js";
|
|
18
|
+
export * from "./tree.js";
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// Spec: 0001-integrations-layers FR-001
|
|
2
|
+
/**
|
|
3
|
+
* Layer 2 of Integrations, the logical layer (commons integrations 0003-integrations-logical): ports as typed records of functions; the observation, its entities
|
|
4
|
+
* and the `Connector` contract with the registry that pins connectors; the abstract tree, schema and profile as constraints, validation with findings at every level, mappings as
|
|
5
|
+
* data that account for every field, acknowledgements and the exchange state machine; the plugin contract of standards; and the conformance suites. Pure: it imports Core
|
|
6
|
+
* and governance and does no effect.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
export * from "./conformance.js";
|
|
11
|
+
export * from "./constraints.js";
|
|
12
|
+
export * from "./exchange.js";
|
|
13
|
+
export * from "./ledger.js";
|
|
14
|
+
export * from "./mapping.js";
|
|
15
|
+
export * from "./observe.js";
|
|
16
|
+
export * from "./plugin.js";
|
|
17
|
+
export * from "./ports.js";
|
|
18
|
+
export * from "./registry.js";
|
|
19
|
+
export * from "./tree.js";
|