@jam-overture/loom 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.
Files changed (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -1,4 +1,5 @@
1
1
  import { ceilingOf, describeCeiling, withCeiling } from "../deadline.js";
2
+ import { describeRegistered } from "../registered.js";
2
3
  import { err } from "../result.js";
3
4
  import { planTreeData, planIsEmpty } from "./plan.js";
4
5
  import { buildDataResolution, EMPTY_DATA_RESOLUTION, } from "./resolution.js";
@@ -17,20 +18,27 @@ const askOne = async (source, params, options) => {
17
18
  if (!registered) {
18
19
  return err({
19
20
  reason: "no-such-source",
20
- detail: `registered: ${options.registry.sources.map((entry) => entry.id).join(", ") || "none"}`,
21
+ detail: `registered: ${describeRegistered(source, options.registry.sources.map((entry) => entry.id))}`,
21
22
  });
22
23
  }
23
24
  const ceiling = ceilingOf(options.ceilingMs, DEFAULT_SOURCE_CEILING_MS);
24
25
  return withCeiling(ceiling, () => err({ reason: "unavailable", detail: `no answer in ${describeCeiling(ceiling)}` }), (signal) => registered.answer(params, options.context, signal));
25
26
  };
27
+ const NO_ANSWERS = Object.freeze([]);
28
+ /** The resolution of a plan that asks nothing, which asked nothing. */
29
+ const EMPTY_RESOLVED_DATA = Object.freeze({
30
+ ...EMPTY_DATA_RESOLUTION,
31
+ answers: NO_ANSWERS,
32
+ });
26
33
  export const resolveDataPlan = async (plan, options) => {
27
34
  if (planIsEmpty(plan))
28
- return EMPTY_DATA_RESOLUTION;
35
+ return EMPTY_RESOLVED_DATA;
29
36
  const answered = await Promise.all(plan.requests.map(async (request) => [
30
37
  request.key,
31
38
  await askOne(request.source, request.params, options),
32
39
  ]));
33
- return buildDataResolution(plan, new Map(answered));
40
+ const answers = Object.freeze(answered);
41
+ return { ...buildDataResolution(plan, new Map(answers)), answers };
34
42
  };
35
43
  /** Plan and resolve in one step, for the ordinary caller that does both. */
36
44
  export const resolveTreeData = async (tree, options) => resolveDataPlan(planTreeData(tree), options);
package/dist/ids.d.ts CHANGED
@@ -39,6 +39,16 @@ export interface IdFactory {
39
39
  readonly intentId: () => IntentId;
40
40
  readonly proposalId: () => ProposalId;
41
41
  }
42
+ /**
43
+ * The body of a random id, which is the part after the prefix.
44
+ *
45
+ * Exported because an application id and a project id are minted outside this
46
+ * module — by the control plane when somebody registers, rather than by an
47
+ * `IdFactory` during a render — and the alternative was either widening that
48
+ * interface with two members no renderer calls, or a second copy of this that
49
+ * drifts.
50
+ */
51
+ export declare const randomIdBody: () => string;
42
52
  export declare const randomIdFactory: IdFactory;
43
53
  /**
44
54
  * Deterministic ids for tests and for replaying a recorded session. Counters
package/dist/ids.js CHANGED
@@ -40,11 +40,21 @@ export const proposalIdSchema = z
40
40
  .brand();
41
41
  const RANDOM_ID_LENGTH = 20;
42
42
  const BASE36_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
43
- const randomBody = () => {
43
+ /**
44
+ * The body of a random id, which is the part after the prefix.
45
+ *
46
+ * Exported because an application id and a project id are minted outside this
47
+ * module — by the control plane when somebody registers, rather than by an
48
+ * `IdFactory` during a render — and the alternative was either widening that
49
+ * interface with two members no renderer calls, or a second copy of this that
50
+ * drifts.
51
+ */
52
+ export const randomIdBody = () => {
44
53
  const bytes = new Uint8Array(RANDOM_ID_LENGTH);
45
54
  globalThis.crypto.getRandomValues(bytes);
46
55
  return Array.from(bytes, (byte) => BASE36_ALPHABET[byte % BASE36_ALPHABET.length] ?? "0").join("");
47
56
  };
57
+ const randomBody = randomIdBody;
48
58
  export const randomIdFactory = {
49
59
  nodeId: () => nodeIdSchema.parse(`n_${randomBody()}`),
50
60
  treeId: () => treeIdSchema.parse(`t_${randomBody()}`),
package/dist/index.d.ts CHANGED
@@ -15,6 +15,7 @@ export * from "./interactivity.js";
15
15
  export * from "./interpretation/index.js";
16
16
  export * from "./json.js";
17
17
  export * from "./paging.js";
18
+ export * from "./patch.js";
18
19
  export * from "./primitive-type.js";
19
20
  export * from "./reserved-props.js";
20
21
  export * from "./result.js";
package/dist/index.js CHANGED
@@ -15,6 +15,7 @@ export * from "./interactivity.js";
15
15
  export * from "./interpretation/index.js";
16
16
  export * from "./json.js";
17
17
  export * from "./paging.js";
18
+ export * from "./patch.js";
18
19
  export * from "./primitive-type.js";
19
20
  export * from "./reserved-props.js";
20
21
  export * from "./result.js";
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The three things a partial update can say about one field, and the one place
3
+ * they are spelled.
4
+ *
5
+ * A store's update method takes the fields a caller wants changed and leaves
6
+ * the rest alone, which is the right shape and leaves one thing unsayable. If
7
+ * an absent field means *leave it alone*, nothing means *remove it* — so a
8
+ * record with an optional field could be given one and never have it taken
9
+ * away. The field that found this was an application's host: a person who
10
+ * empties the box on a settings screen and presses save means *I do not have a
11
+ * host any more*, and the only call available said nothing about the host at
12
+ * all, which renames nothing and reports success.
13
+ *
14
+ * So a patch field carries three states rather than two: a value sets it,
15
+ * `null` clears it, and absent still leaves it alone. `null` rather than an
16
+ * empty string, because an empty string is a value the schemas go on refusing —
17
+ * one spelling of nothing per field is the point, and a second would have every
18
+ * store deciding for itself which of the two it honoured.
19
+ *
20
+ * Clearing **removes the key** rather than setting it to `undefined`. The
21
+ * schemas these patches are parsed against are strict and spell an absent field
22
+ * optional, so a key holding `undefined` is not what a record that never had
23
+ * the field looks like, and the two must not be told apart by which route they
24
+ * arrived by.
25
+ */
26
+ /**
27
+ * One field of a patch: a value to set, or `null` to clear it.
28
+ *
29
+ * Absent is the third state and is not spelled here, because it is the
30
+ * property's own optionality rather than anything this type can say. A field
31
+ * typed `host?: Patch<string>` reads as all three.
32
+ */
33
+ export type Patch<T> = T | null;
34
+ /**
35
+ * A partial update over `T`: every field optional, and every one clearable.
36
+ *
37
+ * `| undefined` is written out rather than left to the `?`, so that a caller
38
+ * may pass a field it has read as absent instead of having to build the object
39
+ * by spreading around it.
40
+ */
41
+ export type PatchOf<T> = {
42
+ readonly [K in keyof T]?: Patch<NonNullable<T[K]>> | undefined;
43
+ };
44
+ /**
45
+ * `subject` with every field the patch mentions applied, and nothing else
46
+ * touched.
47
+ *
48
+ * The result is a new object; the subject is not modified. It is not validated
49
+ * either — a caller parses what comes back against the schema that owns the
50
+ * record, which is what keeps two stores agreeing about what a thing is rather
51
+ * than about what fits in a column.
52
+ */
53
+ export declare const applyPatch: <T extends object>(subject: T, patch: PatchOf<T>) => T;
54
+ //# sourceMappingURL=patch.d.ts.map
package/dist/patch.js ADDED
@@ -0,0 +1,44 @@
1
+ /**
2
+ * The three things a partial update can say about one field, and the one place
3
+ * they are spelled.
4
+ *
5
+ * A store's update method takes the fields a caller wants changed and leaves
6
+ * the rest alone, which is the right shape and leaves one thing unsayable. If
7
+ * an absent field means *leave it alone*, nothing means *remove it* — so a
8
+ * record with an optional field could be given one and never have it taken
9
+ * away. The field that found this was an application's host: a person who
10
+ * empties the box on a settings screen and presses save means *I do not have a
11
+ * host any more*, and the only call available said nothing about the host at
12
+ * all, which renames nothing and reports success.
13
+ *
14
+ * So a patch field carries three states rather than two: a value sets it,
15
+ * `null` clears it, and absent still leaves it alone. `null` rather than an
16
+ * empty string, because an empty string is a value the schemas go on refusing —
17
+ * one spelling of nothing per field is the point, and a second would have every
18
+ * store deciding for itself which of the two it honoured.
19
+ *
20
+ * Clearing **removes the key** rather than setting it to `undefined`. The
21
+ * schemas these patches are parsed against are strict and spell an absent field
22
+ * optional, so a key holding `undefined` is not what a record that never had
23
+ * the field looks like, and the two must not be told apart by which route they
24
+ * arrived by.
25
+ */
26
+ /**
27
+ * `subject` with every field the patch mentions applied, and nothing else
28
+ * touched.
29
+ *
30
+ * The result is a new object; the subject is not modified. It is not validated
31
+ * either — a caller parses what comes back against the schema that owns the
32
+ * record, which is what keeps two stores agreeing about what a thing is rather
33
+ * than about what fits in a column.
34
+ */
35
+ export const applyPatch = (subject, patch) => Object.entries(patch).reduce((applied, [field, change]) => {
36
+ if (change === undefined)
37
+ return applied;
38
+ if (change === null) {
39
+ const { [field]: _cleared, ...kept } = applied;
40
+ return kept;
41
+ }
42
+ return { ...applied, [field]: change };
43
+ }, { ...subject });
44
+ //# sourceMappingURL=patch.js.map
@@ -0,0 +1,51 @@
1
+ import type { ApplicationStore } from "../application/store.js";
2
+ import { type Result } from "../result.js";
3
+ import type { ProjectId } from "./project.js";
4
+ import { type ProjectStore, type ProjectStoreError } from "./store.js";
5
+ /**
6
+ * Closing a project, and the applications it holds.
7
+ *
8
+ * **Above the two stores rather than inside either**
9
+ * ([0289](../../decisions/0289-a-project-is-closed-rather-than-deleted-and-closing-is-a-column-and-a-filter.md)).
10
+ * A project store that reached into an application store to finish its own
11
+ * write would be the coupling both are shaped to avoid — nothing is stored
12
+ * *under* a project, which is why they are two stores and not one.
13
+ *
14
+ * ## What it is instead of
15
+ *
16
+ * A delete, which three stores refuse and
17
+ * [0268](../../decisions/0268-a-page-is-put-back-by-proposing-the-change-that-puts-it-back-and-a-store-never-deletes.md)
18
+ * argued: a project's rows are its applications' trees, revisions, holds and
19
+ * policy history, and removing them destroys the account of what changed that
20
+ * Loom exists to keep. A delete would have cascaded through all of it. This
21
+ * cascades too, and reversibly.
22
+ */
23
+ export type ClosingError = ProjectStoreError
24
+ /**
25
+ * The project closed and an application under it did not.
26
+ *
27
+ * Reported rather than swallowed, and **the project stays closed**: a partial
28
+ * close is recoverable by running it again, where rolling the project back
29
+ * open would make the failure invisible and leave somebody believing their
30
+ * project is still collecting when most of it has stopped.
31
+ */
32
+ | {
33
+ readonly code: "partly-closed";
34
+ readonly projectId: ProjectId;
35
+ readonly detail: string;
36
+ };
37
+ export declare const describeClosingError: (error: ClosingError) => string;
38
+ /**
39
+ * Close the project, then every application in it.
40
+ *
41
+ * **The project first.** If it fails there is nothing to undo, and the
42
+ * applications are still reachable through a project that is still open —
43
+ * which is the state the caller started in. The other order would close
44
+ * applications under a project that then refused to close, leaving a live
45
+ * project full of stopped applications and no record of why.
46
+ *
47
+ * Idempotent, because both `close` calls are: running it again after a partial
48
+ * failure closes what is left and moves nothing that already closed.
49
+ */
50
+ export declare const closeProject: (projects: ProjectStore, applications: ApplicationStore, projectId: ProjectId, at: string) => Promise<Result<undefined, ClosingError>>;
51
+ //# sourceMappingURL=closing.d.ts.map
@@ -0,0 +1,53 @@
1
+ import { err, ok } from "../result.js";
2
+ import { describeProjectStoreError } from "./store.js";
3
+ export const describeClosingError = (error) => error.code === "partly-closed"
4
+ ? `project ${error.projectId} was closed and an application in it was not: ${error.detail}`
5
+ : describeProjectStoreError(error);
6
+ /**
7
+ * Why a listing or a close failed, in one string.
8
+ *
9
+ * `ApplicationStoreError` carries a detail on one member and an id on two, so
10
+ * there is no field common to all of them — the code is the part every member
11
+ * has, and it is what a caller of this can act on.
12
+ */
13
+ const detailOf = (error) => "detail" in error ? error.detail : error.code;
14
+ /**
15
+ * Close the project, then every application in it.
16
+ *
17
+ * **The project first.** If it fails there is nothing to undo, and the
18
+ * applications are still reachable through a project that is still open —
19
+ * which is the state the caller started in. The other order would close
20
+ * applications under a project that then refused to close, leaving a live
21
+ * project full of stopped applications and no record of why.
22
+ *
23
+ * Idempotent, because both `close` calls are: running it again after a partial
24
+ * failure closes what is left and moves nothing that already closed.
25
+ */
26
+ export const closeProject = async (projects, applications, projectId, at) => {
27
+ const closed = await projects.close(projectId, at);
28
+ if (!closed.ok)
29
+ return err(closed.error);
30
+ /**
31
+ * Every application, open or closed, rather than the open ones: the listing
32
+ * is a separate read and a row that closed between the two would otherwise
33
+ * be missed. `close` leaves an already-closed one exactly as it was.
34
+ */
35
+ const held = await applications.list({ closed: "all" });
36
+ if (!held.ok) {
37
+ return err({ code: "partly-closed", projectId, detail: detailOf(held.error) });
38
+ }
39
+ for (const application of held.value) {
40
+ if (application.projectId !== projectId)
41
+ continue;
42
+ const stopped = await applications.close(application.applicationId, at);
43
+ if (!stopped.ok) {
44
+ return err({
45
+ code: "partly-closed",
46
+ projectId,
47
+ detail: `${application.applicationId}: ${detailOf(stopped.error)}`,
48
+ });
49
+ }
50
+ }
51
+ return ok(undefined);
52
+ };
53
+ //# sourceMappingURL=closing.js.map
@@ -0,0 +1,20 @@
1
+ import { type Project } from "./project.js";
2
+ import { type ProjectStore } from "./store.js";
3
+ /**
4
+ * A `ProjectStore` in a `Map`, for a test and for a deployment with no database.
5
+ *
6
+ * The counterpart to `memoryStore`, and it carries the same warning: a `Map`
7
+ * keeps nothing across a process, so on the serverless hosts §3 targets it
8
+ * keeps nothing at all. What it is honestly for is the suite, a lesson, and the
9
+ * first run of an project that has not been given a `DATABASE_URL` yet —
10
+ * where seeing one project called *your project* beats seeing an error.
11
+ *
12
+ * The listing sorts, and the first draft of this file did not — its comment
13
+ * claimed insertion order "happens to be oldest first", which confuses the
14
+ * order rows were *written* with the order they were *created*. A project
15
+ * recorded today with yesterday's `createdAt` is ordinary: it is what importing
16
+ * one, or seeding the default beside projects that already exist, produces. The
17
+ * shared contract writes three out of order and caught it.
18
+ */
19
+ export declare const memoryProjectStore: (seed?: readonly Project[]) => ProjectStore;
20
+ //# sourceMappingURL=memory.d.ts.map
@@ -0,0 +1,97 @@
1
+ import { applyPatch } from "../patch.js";
2
+ import { err, ok } from "../result.js";
3
+ import { projectSchema } from "./project.js";
4
+ import { matchesListing } from "./store.js";
5
+ /**
6
+ * A `ProjectStore` in a `Map`, for a test and for a deployment with no database.
7
+ *
8
+ * The counterpart to `memoryStore`, and it carries the same warning: a `Map`
9
+ * keeps nothing across a process, so on the serverless hosts §3 targets it
10
+ * keeps nothing at all. What it is honestly for is the suite, a lesson, and the
11
+ * first run of an project that has not been given a `DATABASE_URL` yet —
12
+ * where seeing one project called *your project* beats seeing an error.
13
+ *
14
+ * The listing sorts, and the first draft of this file did not — its comment
15
+ * claimed insertion order "happens to be oldest first", which confuses the
16
+ * order rows were *written* with the order they were *created*. A project
17
+ * recorded today with yesterday's `createdAt` is ordinary: it is what importing
18
+ * one, or seeding the default beside projects that already exist, produces. The
19
+ * shared contract writes three out of order and caught it.
20
+ */
21
+ export const memoryProjectStore = (seed = []) => {
22
+ const projects = new Map(seed.map((project) => [project.projectId, project]));
23
+ const read = (projectId) => {
24
+ const found = projects.get(projectId);
25
+ return found === undefined ? err({ code: "not-found", projectId }) : ok(found);
26
+ };
27
+ return {
28
+ create: async (project) => {
29
+ if (projects.has(project.projectId)) {
30
+ return err({ code: "already-exists", projectId: project.projectId });
31
+ }
32
+ /**
33
+ * The partial unique index Postgres carries, by hand (0292). Without it
34
+ * the two stores disagree about whether a repository can be claimed
35
+ * twice — and the one that admits it is the one `pnpm dev` runs on, so
36
+ * the disagreement would be found in production.
37
+ */
38
+ if (project.repository !== undefined &&
39
+ [...projects.values()].some((held) => held.repository === project.repository)) {
40
+ return err({ code: "repository-taken", repository: project.repository });
41
+ }
42
+ projects.set(project.projectId, project);
43
+ return ok(project);
44
+ },
45
+ get: async (projectId) => read(projectId),
46
+ list: async (listing) => ok([...projects.values()]
47
+ .filter((project) => matchesListing(project.closedAt, listing))
48
+ .sort((left, right) => left.createdAt.localeCompare(right.createdAt))),
49
+ rename: async (projectId, to) => {
50
+ const found = read(projectId);
51
+ if (!found.ok)
52
+ return found;
53
+ /**
54
+ * Parsed rather than spread, so a name this store would accept and the
55
+ * database would refuse cannot be told apart by which one you used. The
56
+ * two stores agree about what a project is because they both ask
57
+ * `projectSchema`, and they agree about what a patch means because they
58
+ * both apply it with `applyPatch`.
59
+ *
60
+ * Nothing here is clearable, and that is a property of the record rather
61
+ * than of this call: a project is an id, a name and a date, and all three
62
+ * are required. The first optional field it gains is clearable on the day
63
+ * it is added, with no second spelling of nothing to invent.
64
+ */
65
+ const next = projectSchema.safeParse(applyPatch(found.value, to));
66
+ if (!next.success) {
67
+ return err({ code: "unreadable", projectId, detail: next.error.issues[0]?.message ?? "invalid" });
68
+ }
69
+ projects.set(projectId, next.data);
70
+ return ok(next.data);
71
+ },
72
+ /**
73
+ * Idempotent, and the instant does not move (0289): pressing the button
74
+ * twice must not change the answer to *when did this stop*.
75
+ */
76
+ close: async (projectId, at) => {
77
+ const found = read(projectId);
78
+ if (!found.ok)
79
+ return found;
80
+ if (found.value.closedAt !== undefined)
81
+ return ok(found.value);
82
+ const next = { ...found.value, closedAt: at };
83
+ projects.set(projectId, next);
84
+ return ok(next);
85
+ },
86
+ reopen: async (projectId) => {
87
+ const found = read(projectId);
88
+ if (!found.ok)
89
+ return found;
90
+ /** Spelled as a removal rather than `closedAt: undefined`, which a strict parse refuses. */
91
+ const { closedAt: _was, ...open } = found.value;
92
+ projects.set(projectId, open);
93
+ return ok(open);
94
+ },
95
+ };
96
+ };
97
+ //# sourceMappingURL=memory.js.map
@@ -0,0 +1,90 @@
1
+ /**
2
+ * The grouping a person puts their applications into.
3
+ *
4
+ * Three levels, settled by the maintainer on 12 October: an **account** holds
5
+ * **projects**, and a project holds **applications**. The application is the
6
+ * unit everything is stored and governed under — it owns the pages, the
7
+ * signals, the policy and the credentials — and this is the folder it sits in.
8
+ *
9
+ * **It is organisational and nothing else, deliberately.** A project owns no
10
+ * policy, no members and no credentials today; those were named as later work
11
+ * and are not anticipated here, because a level that owns nothing is cheap to
12
+ * carry and a level that owns the wrong things is expensive to correct. What it
13
+ * has is an identity and a name, which is the whole of what grouping needs.
14
+ *
15
+ * Nothing scoped by an application is also scoped by a project, for the same
16
+ * reason: the project is reachable from the application, so storing it twice
17
+ * would be two places to disagree. When a project does own something — policy
18
+ * inherited by its applications is the likeliest — the edge to travel is
19
+ * `Application.projectId`, which already exists.
20
+ */
21
+ import { z } from "zod";
22
+ export declare const projectIdSchema: z.ZodBranded<z.ZodString, "ProjectId">;
23
+ export type ProjectId = z.infer<typeof projectIdSchema>;
24
+ /** A new project's id, minted when somebody makes one. Random, as an application's is. */
25
+ export declare const newProjectId: () => ProjectId;
26
+ /**
27
+ * The project every application written before projects existed belongs to.
28
+ *
29
+ * Nothing is migrated by guessing (0260, and its successor). The applications
30
+ * that exist belong to the deployment that wrote them, so they go into one
31
+ * project named for it rather than into a distribution somebody invented.
32
+ */
33
+ export declare const DEFAULT_PROJECT_ID: ProjectId;
34
+ /**
35
+ * What a deployment knows about one of its projects, which is as little as a
36
+ * grouping can be and still be one.
37
+ */
38
+ export declare const projectSchema: z.ZodObject<{
39
+ projectId: z.ZodBranded<z.ZodString, "ProjectId">;
40
+ /** What a person calls it. Not unique, not an identifier, and editable. */
41
+ name: z.ZodString;
42
+ createdAt: z.ZodString;
43
+ /**
44
+ * The repository this project's pages live in, or absent (0292).
45
+ *
46
+ * **At most one, and a repository belongs to at most one project**, which
47
+ * is what makes the write-back expressible: the first one is a pull
48
+ * request against the customer's repository (0275), and a pull request has
49
+ * exactly one destination. The uniqueness is the store's to
50
+ * enforce, because two projects claiming one repository is a race rather
51
+ * than a typo.
52
+ *
53
+ * Absent is the ordinary first state and stays legal: a project that keeps
54
+ * its tree in a working copy or in its own database has no repository, and
55
+ * being connected for observation alone needs none at all (0275).
56
+ *
57
+ * Spelled `owner/name`. Not a URL, because the forge is not in the value —
58
+ * a URL would make `github.com/a/b` and `https://github.com/a/b/` two
59
+ * repositories, and the uniqueness above is only as good as the spelling.
60
+ * What understands it is the write-back adapter, which does not exist yet.
61
+ */
62
+ repository: z.ZodOptional<z.ZodString>;
63
+ /**
64
+ * When it was closed, or absent while it is open (0289).
65
+ *
66
+ * Closing is what this store has instead of deleting: a project's rows are
67
+ * its applications' trees, revisions, holds and policy history, and a
68
+ * delete would either orphan them or cascade through the governance record
69
+ * Loom exists to keep.
70
+ *
71
+ * **An instant rather than a flag**, because *when* is the question anybody
72
+ * asks about a closed project — did this stop before or after the thing I
73
+ * am looking at — and a boolean cannot answer it for the same storage.
74
+ */
75
+ closedAt: z.ZodOptional<z.ZodString>;
76
+ }, "strict", z.ZodTypeAny, {
77
+ name: string;
78
+ projectId: string & z.BRAND<"ProjectId">;
79
+ createdAt: string;
80
+ repository?: string | undefined;
81
+ closedAt?: string | undefined;
82
+ }, {
83
+ name: string;
84
+ projectId: string;
85
+ createdAt: string;
86
+ repository?: string | undefined;
87
+ closedAt?: string | undefined;
88
+ }>;
89
+ export type Project = z.infer<typeof projectSchema>;
90
+ //# sourceMappingURL=project.d.ts.map
@@ -0,0 +1,91 @@
1
+ /**
2
+ * The grouping a person puts their applications into.
3
+ *
4
+ * Three levels, settled by the maintainer on 12 October: an **account** holds
5
+ * **projects**, and a project holds **applications**. The application is the
6
+ * unit everything is stored and governed under — it owns the pages, the
7
+ * signals, the policy and the credentials — and this is the folder it sits in.
8
+ *
9
+ * **It is organisational and nothing else, deliberately.** A project owns no
10
+ * policy, no members and no credentials today; those were named as later work
11
+ * and are not anticipated here, because a level that owns nothing is cheap to
12
+ * carry and a level that owns the wrong things is expensive to correct. What it
13
+ * has is an identity and a name, which is the whole of what grouping needs.
14
+ *
15
+ * Nothing scoped by an application is also scoped by a project, for the same
16
+ * reason: the project is reachable from the application, so storing it twice
17
+ * would be two places to disagree. When a project does own something — policy
18
+ * inherited by its applications is the likeliest — the edge to travel is
19
+ * `Application.projectId`, which already exists.
20
+ */
21
+ import { z } from "zod";
22
+ import { idPattern } from "../grammar.js";
23
+ import { randomIdBody } from "../ids.js";
24
+ /*
25
+ * `prj`, which is the prefix an application id wore until 12 October. It moves
26
+ * here rather than being retired because it always meant *the thing with a name
27
+ * that a person organises by*, and that is what a project is now. The ids that
28
+ * were minted under it belong to applications and are migrated to `app_`;
29
+ * nothing holds both meanings at once.
30
+ */
31
+ export const projectIdSchema = z.string().regex(idPattern("prj")).brand();
32
+ /** A new project's id, minted when somebody makes one. Random, as an application's is. */
33
+ export const newProjectId = () => projectIdSchema.parse(`prj_${randomIdBody()}`);
34
+ /**
35
+ * The project every application written before projects existed belongs to.
36
+ *
37
+ * Nothing is migrated by guessing (0260, and its successor). The applications
38
+ * that exist belong to the deployment that wrote them, so they go into one
39
+ * project named for it rather than into a distribution somebody invented.
40
+ */
41
+ export const DEFAULT_PROJECT_ID = projectIdSchema.parse("prj_default");
42
+ /**
43
+ * What a deployment knows about one of its projects, which is as little as a
44
+ * grouping can be and still be one.
45
+ */
46
+ export const projectSchema = z
47
+ .object({
48
+ projectId: projectIdSchema,
49
+ /** What a person calls it. Not unique, not an identifier, and editable. */
50
+ name: z.string().min(1).max(200),
51
+ createdAt: z.string().datetime(),
52
+ /**
53
+ * The repository this project's pages live in, or absent (0292).
54
+ *
55
+ * **At most one, and a repository belongs to at most one project**, which
56
+ * is what makes the write-back expressible: the first one is a pull
57
+ * request against the customer's repository (0275), and a pull request has
58
+ * exactly one destination. The uniqueness is the store's to
59
+ * enforce, because two projects claiming one repository is a race rather
60
+ * than a typo.
61
+ *
62
+ * Absent is the ordinary first state and stays legal: a project that keeps
63
+ * its tree in a working copy or in its own database has no repository, and
64
+ * being connected for observation alone needs none at all (0275).
65
+ *
66
+ * Spelled `owner/name`. Not a URL, because the forge is not in the value —
67
+ * a URL would make `github.com/a/b` and `https://github.com/a/b/` two
68
+ * repositories, and the uniqueness above is only as good as the spelling.
69
+ * What understands it is the write-back adapter, which does not exist yet.
70
+ */
71
+ repository: z
72
+ .string()
73
+ .regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/)
74
+ .max(140)
75
+ .optional(),
76
+ /**
77
+ * When it was closed, or absent while it is open (0289).
78
+ *
79
+ * Closing is what this store has instead of deleting: a project's rows are
80
+ * its applications' trees, revisions, holds and policy history, and a
81
+ * delete would either orphan them or cascade through the governance record
82
+ * Loom exists to keep.
83
+ *
84
+ * **An instant rather than a flag**, because *when* is the question anybody
85
+ * asks about a closed project — did this stop before or after the thing I
86
+ * am looking at — and a boolean cannot answer it for the same storage.
87
+ */
88
+ closedAt: z.string().datetime().optional(),
89
+ })
90
+ .strict();
91
+ //# sourceMappingURL=project.js.map