foldkit-surface 0.1.0 → 0.2.0
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/README.md +257 -34
- package/dist/index.d.mts +56 -60
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +71 -110
- package/dist/index.mjs.map +1 -1
- package/package.json +12 -1
package/dist/index.mjs
CHANGED
|
@@ -1,15 +1,16 @@
|
|
|
1
1
|
import { Optic, Option, Result, Schema } from "effect";
|
|
2
2
|
//#region src/index.ts
|
|
3
3
|
/**
|
|
4
|
-
* `foldkit-surface` —
|
|
4
|
+
* `foldkit-surface` — the observation boundary for a Foldkit application.
|
|
5
5
|
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
6
|
+
* A Surface is a pure projection of the Model: it declares which fields a
|
|
7
|
+
* feature reads and which Messages it may construct, from the application's
|
|
8
|
+
* own Schema rather than a second hand-written interface. `foldkit-remote`,
|
|
9
|
+
* `foldkit-sync`, `foldkit-agent`, and `foldkit-mirror` all read this boundary,
|
|
10
|
+
* and `Module` validates that each Model path has one owner.
|
|
10
11
|
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
12
|
+
* Nothing here runs: the deliverable is the type surface, pinned by
|
|
13
|
+
* `test/inference.test-d.ts`.
|
|
13
14
|
*/
|
|
14
15
|
/**
|
|
15
16
|
* Low-level escape hatch for a focus with no Model path of its own. Prefer the
|
|
@@ -84,7 +85,7 @@ function makeTree(schema, path, optic, get, optional = false, set, owner) {
|
|
|
84
85
|
}, owner);
|
|
85
86
|
node.select = (projection) => {
|
|
86
87
|
const dependencies = mergeDependencies([path, ...projection.dependencies]);
|
|
87
|
-
return optional ? makeProjection(Schema.Option(projection.Model), dependencies,
|
|
88
|
+
return optional ? makeProjection(Schema.Option(projection.Model), dependencies, (root) => Option.map(get(root), (value) => projection.read(value)), projection.metadata) : makeProjection(projection.Model, dependencies, (root) => projection.read(get(root)), projection.metadata);
|
|
88
89
|
};
|
|
89
90
|
return node;
|
|
90
91
|
}
|
|
@@ -100,94 +101,59 @@ function mergeDependencies(dependencies) {
|
|
|
100
101
|
}
|
|
101
102
|
return merged;
|
|
102
103
|
}
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
...current,
|
|
120
|
-
select: mergeRelation(current.select, connection.select)
|
|
121
|
-
});
|
|
122
|
-
}
|
|
123
|
-
return [...merged.values()];
|
|
124
|
-
}
|
|
125
|
-
/** Unions two relation slices for the same target: fields, windows, and nested relations. */
|
|
126
|
-
function mergeRelation(current, next) {
|
|
127
|
-
const fields = [...current.fields];
|
|
128
|
-
const seen = new Set(fields);
|
|
129
|
-
for (const field of next.fields) {
|
|
130
|
-
if (seen.has(field)) continue;
|
|
131
|
-
seen.add(field);
|
|
132
|
-
fields.push(field);
|
|
133
|
-
}
|
|
134
|
-
const windows = {
|
|
135
|
-
...current.windows,
|
|
136
|
-
...next.windows
|
|
137
|
-
};
|
|
138
|
-
const relations = mergeRelations(current.relations, next.relations);
|
|
139
|
-
return {
|
|
140
|
-
entity: current.entity,
|
|
141
|
-
fields,
|
|
142
|
-
...Object.keys(windows).length === 0 ? {} : { windows },
|
|
143
|
-
...relations === void 0 ? {} : { relations }
|
|
144
|
-
};
|
|
145
|
-
}
|
|
146
|
-
/** Unions two relation maps field by field; a field in both merges recursively. */
|
|
147
|
-
function mergeRelations(current, next) {
|
|
148
|
-
if (current === void 0) return next;
|
|
149
|
-
if (next === void 0) return current;
|
|
150
|
-
const merged = { ...current };
|
|
151
|
-
for (const [field, relation] of Object.entries(next)) {
|
|
152
|
-
const existing = merged[field];
|
|
153
|
-
merged[field] = existing === void 0 ? relation : mergeRelation(existing, relation);
|
|
154
|
-
}
|
|
155
|
-
return merged;
|
|
156
|
-
}
|
|
157
|
-
/** Unions requirements for the same entity + id, dropping duplicate fields. */
|
|
158
|
-
function mergeRequirements(requirements) {
|
|
104
|
+
/** Marks a `Metadata` value. Its entries are private to this module. */
|
|
105
|
+
const MetadataTypeId = Symbol.for("foldkit-surface/Metadata");
|
|
106
|
+
const noEntries = /* @__PURE__ */ new Map();
|
|
107
|
+
const noValues = Object.freeze([]);
|
|
108
|
+
const entriesByMetadata = /* @__PURE__ */ new WeakMap();
|
|
109
|
+
const makeMetadata = (entries) => {
|
|
110
|
+
const metadata = Object.freeze(Object.defineProperty({}, MetadataTypeId, { value: MetadataTypeId }));
|
|
111
|
+
entriesByMetadata.set(metadata, entries);
|
|
112
|
+
return metadata;
|
|
113
|
+
};
|
|
114
|
+
const isMetadata = (value) => typeof value === "object" && value !== null && entriesByMetadata.has(value);
|
|
115
|
+
/** A value this module did not make has no entries. */
|
|
116
|
+
const entriesOf = (metadata) => entriesByMetadata.get(metadata) ?? noEntries;
|
|
117
|
+
const emptyMetadata = makeMetadata(noEntries);
|
|
118
|
+
function combineMetadata(parts) {
|
|
119
|
+
if (parts.length === 1) return isMetadata(parts[0]) ? parts[0] : emptyMetadata;
|
|
159
120
|
const grouped = /* @__PURE__ */ new Map();
|
|
160
|
-
for (const
|
|
161
|
-
const key = `${requirement.entity}\u0000${requirement.id}`;
|
|
121
|
+
for (const part of parts) for (const [key, values] of entriesOf(part)) {
|
|
162
122
|
const group = grouped.get(key);
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
...mergeRelation(group ?? {
|
|
166
|
-
entity: requirement.entity,
|
|
167
|
-
fields: []
|
|
168
|
-
}, requirement),
|
|
169
|
-
id: requirement.id,
|
|
170
|
-
...live ? { live } : {}
|
|
171
|
-
});
|
|
123
|
+
if (group === void 0) grouped.set(key, [...values]);
|
|
124
|
+
else group.push(...values);
|
|
172
125
|
}
|
|
173
|
-
|
|
126
|
+
if (grouped.size === 0) return emptyMetadata;
|
|
127
|
+
const merged = /* @__PURE__ */ new Map();
|
|
128
|
+
for (const [key, values] of grouped) merged.set(key, Object.freeze([...key.merge(values)]));
|
|
129
|
+
return makeMetadata(merged);
|
|
174
130
|
}
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
131
|
+
const Metadata = {
|
|
132
|
+
/**
|
|
133
|
+
* Declares an interpreter's slot. Call once per package, at module level:
|
|
134
|
+
* entries are found by the key object, so two copies of a package (a
|
|
135
|
+
* duplicated install, a reloaded module) do not see each other's entries.
|
|
136
|
+
*/
|
|
137
|
+
key: (name, options) => {
|
|
138
|
+
const key = {
|
|
139
|
+
name,
|
|
140
|
+
merge: options.merge,
|
|
141
|
+
summarize: options.summarize,
|
|
142
|
+
of: (...values) => values.length === 0 ? emptyMetadata : makeMetadata(/* @__PURE__ */ new Map([[key, Object.freeze([...key.merge(values)])]])),
|
|
143
|
+
get: (metadata) => entriesOf(metadata).get(key) ?? noValues
|
|
144
|
+
};
|
|
145
|
+
return key;
|
|
146
|
+
},
|
|
147
|
+
summarize: (metadata) => [...entriesOf(metadata)].map(([key, values]) => ({
|
|
148
|
+
name: key.name,
|
|
149
|
+
entries: values.map((value) => key.summarize(value))
|
|
150
|
+
}))
|
|
184
151
|
};
|
|
185
|
-
function makeProjection(Model, dependencies,
|
|
152
|
+
function makeProjection(Model, dependencies, read, metadata = emptyMetadata) {
|
|
186
153
|
return {
|
|
187
154
|
Model,
|
|
188
155
|
dependencies,
|
|
189
|
-
|
|
190
|
-
connections,
|
|
156
|
+
metadata,
|
|
191
157
|
read
|
|
192
158
|
};
|
|
193
159
|
}
|
|
@@ -203,8 +169,7 @@ const Projection = {
|
|
|
203
169
|
of: (schema) => (selection) => {
|
|
204
170
|
const picked = {};
|
|
205
171
|
const dependencies = [];
|
|
206
|
-
const
|
|
207
|
-
const connections = [];
|
|
172
|
+
const metadata = [];
|
|
208
173
|
const readers = [];
|
|
209
174
|
for (const key of Object.keys(selection)) {
|
|
210
175
|
const choice = selection[key];
|
|
@@ -215,8 +180,7 @@ const Projection = {
|
|
|
215
180
|
const nested = choice;
|
|
216
181
|
picked[key] = nested.Model;
|
|
217
182
|
dependencies.push(...nested.dependencies);
|
|
218
|
-
|
|
219
|
-
connections.push(...nested.connections);
|
|
183
|
+
metadata.push(nested.metadata);
|
|
220
184
|
readers.push([key, (root) => nested.read(propertyReader(root, key))]);
|
|
221
185
|
}
|
|
222
186
|
}
|
|
@@ -225,21 +189,19 @@ const Projection = {
|
|
|
225
189
|
for (const [key, reader] of readers) out[key] = reader(root);
|
|
226
190
|
return out;
|
|
227
191
|
};
|
|
228
|
-
return makeProjection(objectSchema(picked), mergeDependencies(dependencies),
|
|
192
|
+
return makeProjection(objectSchema(picked), mergeDependencies(dependencies), read, combineMetadata(metadata));
|
|
229
193
|
},
|
|
230
194
|
struct: (entries) => {
|
|
231
195
|
const picked = {};
|
|
232
196
|
const dependencies = [];
|
|
233
|
-
const
|
|
234
|
-
const connections = [];
|
|
197
|
+
const metadata = [];
|
|
235
198
|
const readers = [];
|
|
236
199
|
for (const key of Object.keys(entries)) {
|
|
237
200
|
const entry = entries[key];
|
|
238
201
|
if ("dependencies" in entry) {
|
|
239
202
|
picked[key] = entry.Model;
|
|
240
203
|
dependencies.push(...entry.dependencies);
|
|
241
|
-
|
|
242
|
-
connections.push(...entry.connections);
|
|
204
|
+
metadata.push(entry.metadata);
|
|
243
205
|
readers.push([key, entry.read]);
|
|
244
206
|
} else {
|
|
245
207
|
picked[key] = entry.Schema;
|
|
@@ -252,7 +214,7 @@ const Projection = {
|
|
|
252
214
|
for (const [key, reader] of readers) out[key] = reader(root);
|
|
253
215
|
return out;
|
|
254
216
|
};
|
|
255
|
-
return makeProjection(objectSchema(picked), mergeDependencies(dependencies),
|
|
217
|
+
return makeProjection(objectSchema(picked), mergeDependencies(dependencies), read, combineMetadata(metadata));
|
|
256
218
|
},
|
|
257
219
|
/**
|
|
258
220
|
* Maps a Projection over an array: `array(p): Projection<ReadonlyArray<Root>,
|
|
@@ -262,16 +224,14 @@ const Projection = {
|
|
|
262
224
|
array: (projection) => ({
|
|
263
225
|
Model: Schema.Array(projection.Model),
|
|
264
226
|
dependencies: projection.dependencies,
|
|
265
|
-
|
|
266
|
-
connections: projection.connections,
|
|
227
|
+
metadata: projection.metadata,
|
|
267
228
|
read: (root) => root.map((value) => projection.read(value))
|
|
268
229
|
}),
|
|
269
230
|
/** Maps a Projection inside an Option, preserving absence. */
|
|
270
231
|
option: (projection) => ({
|
|
271
232
|
Model: Schema.Option(projection.Model),
|
|
272
233
|
dependencies: projection.dependencies,
|
|
273
|
-
|
|
274
|
-
connections: projection.connections,
|
|
234
|
+
metadata: projection.metadata,
|
|
275
235
|
read: (root) => Option.map(root, (value) => projection.read(value))
|
|
276
236
|
}),
|
|
277
237
|
read: (projection, root) => projection.read(root),
|
|
@@ -283,8 +243,7 @@ const Projection = {
|
|
|
283
243
|
fromReader: (Model, read, options) => ({
|
|
284
244
|
Model,
|
|
285
245
|
dependencies: options?.dependencies ?? [],
|
|
286
|
-
|
|
287
|
-
connections: options?.connections ?? [],
|
|
246
|
+
metadata: options?.metadata ?? emptyMetadata,
|
|
288
247
|
read
|
|
289
248
|
}),
|
|
290
249
|
/**
|
|
@@ -355,7 +314,7 @@ const Projection = {
|
|
|
355
314
|
};
|
|
356
315
|
}
|
|
357
316
|
};
|
|
358
|
-
const isProjection = (value) => typeof value === "object" && value !== null &&
|
|
317
|
+
const isProjection = (value) => typeof value === "object" && value !== null && typeof value.read === "function" && isMetadata(value.metadata);
|
|
359
318
|
const makeScope = (config) => {
|
|
360
319
|
const owner = {};
|
|
361
320
|
return {
|
|
@@ -501,7 +460,7 @@ const Surface = {
|
|
|
501
460
|
owns: [],
|
|
502
461
|
observes: projection.dependencies,
|
|
503
462
|
messages: surface.messages.map(messageTag).filter((tag) => tag !== void 0),
|
|
504
|
-
|
|
463
|
+
metadata: Metadata.summarize(projection.metadata)
|
|
505
464
|
};
|
|
506
465
|
},
|
|
507
466
|
/**
|
|
@@ -513,12 +472,14 @@ const Surface = {
|
|
|
513
472
|
return {
|
|
514
473
|
name: surface.name,
|
|
515
474
|
dependencies: projection.dependencies,
|
|
516
|
-
|
|
475
|
+
metadata: Metadata.summarize(projection.metadata),
|
|
517
476
|
emits: surface.messages
|
|
518
477
|
};
|
|
519
478
|
}
|
|
520
479
|
};
|
|
521
480
|
const label = (contract) => `${contract.kind}:${contract.name}`;
|
|
481
|
+
/** Metadata summaries are application data (a query's input), so they cannot break the table. */
|
|
482
|
+
const tableCell = (text) => text.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r\n?|\n/g, " ");
|
|
522
483
|
const pathKey = (path) => path.join(".");
|
|
523
484
|
const isPrefix = (prefix, path) => prefix.length <= path.length && prefix.every((segment, index) => segment === path[index]);
|
|
524
485
|
const toContract = (item) => "contract" in item ? item.contract : "projection" in item ? Surface.contract(item, void 0) : item;
|
|
@@ -650,8 +611,8 @@ const Module = {
|
|
|
650
611
|
const owner = row.owner === void 0 ? "LOCAL" : `${row.owner.kind.toUpperCase()} ${row.owner.name}`;
|
|
651
612
|
lines.push(`${last ? "└── " : "├── "}${pathKey(row.path).padEnd(width)} ${owner}`);
|
|
652
613
|
});
|
|
653
|
-
lines.push("```", "", "| Contract | Owns | Observes | Messages |
|
|
654
|
-
for (const contract of manifest.contracts) lines.push(`| ${contract.kind}:${contract.name} | ${contract.owns.map(pathKey).join(", ")} | ${contract.observes.map(pathKey).join(", ")} | ${contract.messages.join(", ")} | ${contract.
|
|
614
|
+
lines.push("```", "", "| Contract | Owns | Observes | Messages | Metadata |", "| --- | --- | --- | --- | --- |");
|
|
615
|
+
for (const contract of manifest.contracts) lines.push(`| ${contract.kind}:${contract.name} | ${contract.owns.map(pathKey).join(", ")} | ${contract.observes.map(pathKey).join(", ")} | ${contract.messages.join(", ")} | ${tableCell(contract.metadata.map((summary) => `${summary.name}: ${summary.entries.join(", ")}`).join("; "))} |`);
|
|
655
616
|
if (manifest.findings.length > 0) {
|
|
656
617
|
lines.push("", "## Findings", "");
|
|
657
618
|
for (const finding of manifest.findings) lines.push(`- **${finding.rule}** ${finding.message}`);
|
|
@@ -686,6 +647,6 @@ const Module = {
|
|
|
686
647
|
}
|
|
687
648
|
};
|
|
688
649
|
//#endregion
|
|
689
|
-
export { MessageSet, ModelRef, Module, Projection,
|
|
650
|
+
export { MessageSet, Metadata, MetadataTypeId, ModelRef, Module, Projection, Surface };
|
|
690
651
|
|
|
691
652
|
//# sourceMappingURL=index.mjs.map
|