functionalscript 0.38.0 → 0.40.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 (137) hide show
  1. package/README.md +1 -1
  2. package/fjs/bnf/descent/module.f.d.ts +43 -2
  3. package/fjs/bnf/descent/module.f.js +37 -12
  4. package/fjs/bnf/descent/proof.f.d.ts +1 -0
  5. package/fjs/bnf/descent/proof.f.js +73 -32
  6. package/fjs/bnf/ll1/module.f.js +2 -2
  7. package/fjs/bnf/token_symbol/module.f.d.ts +38 -0
  8. package/fjs/bnf/token_symbol/module.f.js +48 -0
  9. package/fjs/bnf/token_symbol/proof.f.d.ts +10 -0
  10. package/fjs/bnf/token_symbol/proof.f.js +37 -0
  11. package/fjs/cas/cli/module.f.js +6 -9
  12. package/fjs/cas/evo/module.f.d.ts +77 -13
  13. package/fjs/cas/evo/module.f.js +130 -18
  14. package/fjs/cas/evo/proof.f.d.ts +7 -0
  15. package/fjs/cas/evo/proof.f.js +120 -1
  16. package/fjs/cas/module.f.js +64 -37
  17. package/fjs/cas/proof.f.d.ts +3 -9
  18. package/fjs/cas/proof.f.js +94 -74
  19. package/fjs/ci/bun/module.f.js +3 -3
  20. package/fjs/ci/common/module.f.d.ts +1 -2
  21. package/fjs/ci/common/module.f.js +1 -5
  22. package/fjs/ci/config/module.f.d.ts +11 -8
  23. package/fjs/ci/config/module.f.js +24 -9
  24. package/fjs/ci/deno/module.f.js +3 -3
  25. package/fjs/ci/module.f.js +13 -7
  26. package/fjs/ci/nix/module.f.d.ts +61 -0
  27. package/fjs/ci/nix/module.f.js +92 -0
  28. package/fjs/ci/nix/proof.f.d.ts +23 -0
  29. package/fjs/ci/nix/proof.f.js +109 -0
  30. package/fjs/ci/node/module.f.d.ts +23 -1
  31. package/fjs/ci/node/module.f.js +58 -12
  32. package/fjs/ci/proof.f.d.ts +2 -0
  33. package/fjs/ci/proof.f.js +49 -9
  34. package/fjs/cli/module.f.js +2 -2
  35. package/fjs/common/monoid/module.f.d.ts +46 -2
  36. package/fjs/common/monoid/module.f.js +44 -0
  37. package/fjs/common/monoid/proof.f.d.ts +5 -0
  38. package/fjs/common/monoid/proof.f.js +27 -1
  39. package/fjs/dev/module.f.d.ts +1 -0
  40. package/fjs/dev/module.f.js +38 -27
  41. package/fjs/dev/update/module.f.d.ts +11 -0
  42. package/fjs/dev/update/module.f.js +20 -0
  43. package/fjs/dev/update/proof.f.d.ts +7 -0
  44. package/fjs/dev/update/proof.f.js +35 -0
  45. package/fjs/djs/ast/module.f.d.ts +47 -0
  46. package/fjs/djs/ast/module.f.js +9 -0
  47. package/fjs/djs/module.f.js +5 -8
  48. package/fjs/djs/parser/module.f.d.ts +3 -0
  49. package/fjs/djs/parser/module.f.js +17 -0
  50. package/fjs/djs/tokenizer/module.f.js +2 -2
  51. package/fjs/djs/tokenizer/proof.f.d.ts +1 -0
  52. package/fjs/djs/tokenizer/proof.f.js +70 -16
  53. package/fjs/djs/transpiler/module.f.js +6 -6
  54. package/fjs/effects/eff/module.f.d.ts +72 -0
  55. package/fjs/effects/eff/module.f.js +46 -0
  56. package/fjs/effects/eff/proof.f.d.ts +11 -0
  57. package/fjs/effects/eff/proof.f.js +58 -0
  58. package/fjs/effects/list/module.f.d.ts +11 -5
  59. package/fjs/effects/list/module.f.js +2 -1
  60. package/fjs/effects/memory/proof.f.js +7 -8
  61. package/fjs/effects/module.f.d.ts +334 -52
  62. package/fjs/effects/module.f.js +253 -45
  63. package/fjs/effects/node/memory/proof.js +3 -2
  64. package/fjs/effects/node/module.d.ts +3 -3
  65. package/fjs/effects/node/module.f.d.ts +18 -8
  66. package/fjs/effects/node/module.f.js +31 -11
  67. package/fjs/effects/node/module.js +12 -12
  68. package/fjs/effects/node/proof.f.d.ts +1 -0
  69. package/fjs/effects/node/proof.f.js +32 -11
  70. package/fjs/effects/node/virtual/module.f.js +1 -1
  71. package/fjs/effects/proof.f.d.ts +32 -6
  72. package/fjs/effects/proof.f.js +131 -39
  73. package/fjs/emergent_testing/all.test.js +2 -1
  74. package/fjs/emergent_testing/module.f.d.ts +3 -3
  75. package/fjs/emergent_testing/module.f.js +63 -49
  76. package/fjs/emergent_testing/proof.f.d.ts +4 -0
  77. package/fjs/emergent_testing/proof.f.js +54 -21
  78. package/fjs/emergent_testing/scenarios/thenable.pass.js +1 -1
  79. package/fjs/fsc/module.f.js +4 -4
  80. package/fjs/fsm/module.f.js +1 -1
  81. package/fjs/js/tokenizer/module.f.d.ts +1 -0
  82. package/fjs/js/tokenizer/module.f.js +13 -6
  83. package/fjs/{cas/mcp → mcp/cas}/module.f.d.ts +3 -25
  84. package/fjs/{cas/mcp → mcp/cas}/module.f.js +26 -64
  85. package/fjs/mcp/evo/module.f.d.ts +27 -0
  86. package/fjs/mcp/evo/module.f.js +94 -0
  87. package/fjs/{cas/evo/mcp → mcp/evo}/proof.f.d.ts +2 -0
  88. package/fjs/{cas/evo/mcp → mcp/evo}/proof.f.js +40 -9
  89. package/fjs/mcp/module.f.d.ts +54 -237
  90. package/fjs/mcp/module.f.js +55 -258
  91. package/fjs/mcp/proof.f.d.ts +43 -32
  92. package/fjs/mcp/proof.f.js +509 -200
  93. package/fjs/media/nix/module.f.d.ts +30 -0
  94. package/fjs/media/nix/module.f.js +166 -0
  95. package/fjs/media/nix/proof.f.d.ts +32 -0
  96. package/fjs/media/nix/proof.f.js +127 -0
  97. package/fjs/media/type/module.f.js +2 -2
  98. package/fjs/media/type/proof.f.js +7 -10
  99. package/fjs/module.f.js +5 -9
  100. package/fjs/protocol/json_rpc/module.f.d.ts +114 -0
  101. package/fjs/{media/json/rpc → protocol/json_rpc}/module.f.js +3 -3
  102. package/fjs/{media/json/rpc → protocol/json_rpc}/proof.f.js +3 -3
  103. package/fjs/protocol/mcp/module.f.d.ts +239 -0
  104. package/fjs/protocol/mcp/module.f.js +272 -0
  105. package/fjs/protocol/mcp/proof.f.d.ts +34 -0
  106. package/fjs/protocol/mcp/proof.f.js +208 -0
  107. package/fjs/{mcp → protocol/mcp}/stdio/module.f.d.ts +7 -7
  108. package/fjs/{mcp → protocol/mcp}/stdio/module.f.js +22 -22
  109. package/fjs/{mcp → protocol/mcp}/stdio/proof.f.js +9 -9
  110. package/fjs/types/bigint/module.f.js +4 -3
  111. package/fjs/types/bit_vec/module.f.js +5 -15
  112. package/fjs/types/btree/remove/module.f.d.ts +5 -0
  113. package/fjs/types/btree/remove/module.f.js +12 -0
  114. package/fjs/types/list/module.f.d.ts +21 -0
  115. package/fjs/types/list/module.f.js +17 -0
  116. package/fjs/types/list/proof.f.d.ts +1 -0
  117. package/fjs/types/list/proof.f.js +24 -1
  118. package/fjs/types/number/module.f.js +2 -1
  119. package/fjs/types/range_map/module.f.d.ts +14 -13
  120. package/fjs/types/range_map/module.f.js +18 -13
  121. package/fjs/types/range_map/proof.f.js +26 -39
  122. package/fjs/types/range_set/module.f.d.ts +5 -0
  123. package/fjs/types/range_set/module.f.js +16 -0
  124. package/fjs/types/range_set/proof.f.d.ts +1 -0
  125. package/fjs/types/range_set/proof.f.js +19 -0
  126. package/fjs/types/string/module.f.js +10 -2
  127. package/fjs/website/module.f.js +2 -3
  128. package/package.json +5 -5
  129. package/fjs/cas/evo/mcp/module.f.d.ts +0 -19
  130. package/fjs/cas/evo/mcp/module.f.js +0 -56
  131. package/fjs/cas/mcp/proof.f.d.ts +0 -45
  132. package/fjs/cas/mcp/proof.f.js +0 -545
  133. package/fjs/ci/playwright/module.f.d.ts +0 -2
  134. package/fjs/ci/playwright/module.f.js +0 -25
  135. package/fjs/media/json/rpc/module.f.d.ts +0 -114
  136. /package/fjs/{media/json/rpc → protocol/json_rpc}/proof.f.d.ts +0 -0
  137. /package/fjs/{mcp → protocol/mcp}/stdio/proof.f.d.ts +0 -0
@@ -8,13 +8,21 @@ import { sort } from '../../types/object/module.f.js';
8
8
  // DjsTokenWithMetadata carries bigint fields (bf, bigint value) that JSON.stringify can't
9
9
  // serialize — reuse the same djs stringifyAsTree serializer tokenizeString uses internally.
10
10
  const stringify = stringifyAsTree(sort);
11
+ // 'line:column' of the error token `s` tokenizes to, or 'no error'. Collapsing the
12
+ // position to one string keeps an expectation readable as the caret a reader would
13
+ // draw, instead of two separate assertions per case.
14
+ const errorAt = (s) => {
15
+ const found = toArray(tokenizeJs(stringToList(s))('a.js'))
16
+ .find(t => t.token.kind === 'error');
17
+ return found === undefined ? 'no error' : `${found.metadata.line}:${found.metadata.column}`;
18
+ };
11
19
  export const proof = {
12
20
  isValid: [() => {
13
21
  const m = descentParser(jsGrammar());
14
22
  const expect = (s, expected) => {
15
23
  const cp = toArray(stringToCodePointList(s));
16
24
  const mr = descentParserCpOnly(m, '', cp);
17
- const success = mr[1] && mr[2] === cp.length;
25
+ const success = mr.success && mr.idx === cp.length;
18
26
  assertEq(success, expected, JSON.stringify([s, mr]));
19
27
  };
20
28
  expect('"', false);
@@ -51,7 +59,7 @@ export const proof = {
51
59
  const m = descentParser(jsGrammar());
52
60
  const cp = toArray(stringToCodePointList('tr'));
53
61
  const mr = descentParserCpOnly(m, '', cp);
54
- const seq = mr[0].sequence[0];
62
+ const seq = mr.ast.sequence[0];
55
63
  assert(!(seq instanceof Array), JSON.stringify(mr));
56
64
  assertEq(seq.tag, 'id', JSON.stringify(mr));
57
65
  },
@@ -59,7 +67,7 @@ export const proof = {
59
67
  const m = descentParser(jsGrammar());
60
68
  const cp = toArray(stringToCodePointList('"tr"'));
61
69
  const mr = descentParserCpOnly(m, '', cp);
62
- const seq = mr[0].sequence[0];
70
+ const seq = mr.ast.sequence[0];
63
71
  assert(!(seq instanceof Array), JSON.stringify(mr));
64
72
  assertEq(seq.tag, 'string', JSON.stringify(mr));
65
73
  },
@@ -67,7 +75,7 @@ export const proof = {
67
75
  const m = descentParser(jsGrammar());
68
76
  const cp = toArray(stringToCodePointList('56.7e+5'));
69
77
  const mr = descentParserCpOnly(m, '', cp);
70
- const seq = mr[0].sequence[0];
78
+ const seq = mr.ast.sequence[0];
71
79
  assert(!(seq instanceof Array), JSON.stringify(mr));
72
80
  assertEq(seq.tag, 'number', JSON.stringify(mr));
73
81
  },
@@ -75,7 +83,7 @@ export const proof = {
75
83
  const m = descentParser(jsGrammar());
76
84
  const cp = toArray(stringToCodePointList('56n'));
77
85
  const mr = descentParserCpOnly(m, '', cp);
78
- const seq = mr[0].sequence[0];
86
+ const seq = mr.ast.sequence[0];
79
87
  assert(!(seq instanceof Array), JSON.stringify(mr));
80
88
  assertEq(seq.tag, 'number', JSON.stringify(mr));
81
89
  },
@@ -83,7 +91,7 @@ export const proof = {
83
91
  const m = descentParser(jsGrammar());
84
92
  const cp = toArray(stringToCodePointList('*'));
85
93
  const mr = descentParserCpOnly(m, '', cp);
86
- const seq = mr[0].sequence[0];
94
+ const seq = mr.ast.sequence[0];
87
95
  assert(!(seq instanceof Array), JSON.stringify(mr));
88
96
  assertEq(seq.tag, '*', JSON.stringify(mr));
89
97
  },
@@ -91,7 +99,7 @@ export const proof = {
91
99
  const m = descentParser(jsGrammar());
92
100
  const cp = toArray(stringToCodePointList('**'));
93
101
  const mr = descentParserCpOnly(m, '', cp);
94
- const seq = mr[0].sequence[0];
102
+ const seq = mr.ast.sequence[0];
95
103
  assert(!(seq instanceof Array), JSON.stringify(mr));
96
104
  assertEq(seq.tag, '**', JSON.stringify(mr));
97
105
  },
@@ -99,7 +107,7 @@ export const proof = {
99
107
  const m = descentParser(jsGrammar());
100
108
  const cp = toArray(stringToCodePointList('=>'));
101
109
  const mr = descentParserCpOnly(m, '', cp);
102
- const seq = mr[0].sequence[0];
110
+ const seq = mr.ast.sequence[0];
103
111
  assert(!(seq instanceof Array), JSON.stringify(mr));
104
112
  assertEq(seq.tag, '=>', JSON.stringify(mr));
105
113
  },
@@ -107,7 +115,7 @@ export const proof = {
107
115
  const m = descentParser(jsGrammar());
108
116
  const cp = toArray(stringToCodePointList('=='));
109
117
  const mr = descentParserCpOnly(m, '', cp);
110
- const seq = mr[0].sequence[0];
118
+ const seq = mr.ast.sequence[0];
111
119
  assert(!(seq instanceof Array), JSON.stringify(mr));
112
120
  assert(!(seq.tag !== '=='), JSON.stringify(mr));
113
121
  },
@@ -115,7 +123,7 @@ export const proof = {
115
123
  const m = descentParser(jsGrammar());
116
124
  const cp = toArray(stringToCodePointList('==='));
117
125
  const mr = descentParserCpOnly(m, '', cp);
118
- const seq = mr[0].sequence[0];
126
+ const seq = mr.ast.sequence[0];
119
127
  assert(!(seq instanceof Array), JSON.stringify(mr));
120
128
  assert(!(seq.tag !== '==='), JSON.stringify(mr));
121
129
  },
@@ -123,7 +131,7 @@ export const proof = {
123
131
  const m = descentParser(jsGrammar());
124
132
  const cp = toArray(stringToCodePointList('='));
125
133
  const mr = descentParserCpOnly(m, '', cp);
126
- const seq = mr[0].sequence[0];
134
+ const seq = mr.ast.sequence[0];
127
135
  assert(!(seq instanceof Array), JSON.stringify(mr));
128
136
  assertEq(seq.tag, '=', JSON.stringify(mr));
129
137
  },
@@ -131,7 +139,7 @@ export const proof = {
131
139
  const m = descentParser(jsGrammar());
132
140
  const cp = toArray(stringToCodePointList(' '));
133
141
  const mr = descentParserCpOnly(m, '', cp);
134
- const seq = mr[0].sequence[0];
142
+ const seq = mr.ast.sequence[0];
135
143
  assert(!(seq instanceof Array), JSON.stringify(mr));
136
144
  assertEq(seq.tag, ' ', JSON.stringify(mr));
137
145
  },
@@ -139,7 +147,7 @@ export const proof = {
139
147
  const m = descentParser(jsGrammar());
140
148
  const cp = toArray(stringToCodePointList('\n'));
141
149
  const mr = descentParserCpOnly(m, '', cp);
142
- const seq = mr[0].sequence[0];
150
+ const seq = mr.ast.sequence[0];
143
151
  assert(!(seq instanceof Array), JSON.stringify(mr));
144
152
  assertEq(seq.tag, '\n', JSON.stringify(mr));
145
153
  },
@@ -147,7 +155,7 @@ export const proof = {
147
155
  const m = descentParser(jsGrammar());
148
156
  const cp = toArray(stringToCodePointList('/\n'));
149
157
  const mr = descentParserCpOnly(m, '', cp);
150
- const seq = mr[0].sequence[0];
158
+ const seq = mr.ast.sequence[0];
151
159
  assert(!(seq instanceof Array), JSON.stringify(mr));
152
160
  assertEq(seq.tag, '/', JSON.stringify(mr));
153
161
  },
@@ -155,7 +163,7 @@ export const proof = {
155
163
  const m = descentParser(jsGrammar());
156
164
  const cp = toArray(stringToCodePointList('//\n'));
157
165
  const mr = descentParserCpOnly(m, '', cp);
158
- const seq = mr[0].sequence[0];
166
+ const seq = mr.ast.sequence[0];
159
167
  assert(!(seq instanceof Array), JSON.stringify(mr));
160
168
  assertEq(seq.tag, 'comment', JSON.stringify(mr));
161
169
  },
@@ -163,7 +171,7 @@ export const proof = {
163
171
  const m = descentParser(jsGrammar());
164
172
  const cp = toArray(stringToCodePointList('/*1*/'));
165
173
  const mr = descentParserCpOnly(m, '', cp);
166
- const seq = mr[0].sequence[0];
174
+ const seq = mr.ast.sequence[0];
167
175
  assert(!(seq instanceof Array), JSON.stringify(mr));
168
176
  assertEq(seq.tag, 'comment', JSON.stringify(mr));
169
177
  }
@@ -1056,6 +1064,52 @@ export const proof = {
1056
1064
  assertEq(JSON.stringify(result), '[{"token":{"kind":"error","message":"invalid token"},"metadata":{"path":"a.js","line":1,"column":2}}]');
1057
1065
  },
1058
1066
  ],
1067
+ // Where an error token is reported. The `tokenizer` group above checks that
1068
+ // these inputs are rejected at all, through the metadata-free
1069
+ // `tokenizeString`; here the same shapes go through `tokenizeJs` so the
1070
+ // position is pinned too.
1071
+ errorPosition: [
1072
+ () => {
1073
+ // input that tokenizes cleanly produces no error token at all —
1074
+ // without this the helper's own no-error branch never runs
1075
+ assertEq(errorAt('x'), 'no error');
1076
+ assertEq(errorAt('{ "a": 1 }'), 'no error');
1077
+ },
1078
+ () => {
1079
+ // a character no rule accepts: reported where it stands
1080
+ assertEq(errorAt('ᄑ'), '1:1');
1081
+ },
1082
+ () => {
1083
+ // after a good prefix, the position advances past it
1084
+ assertEq(errorAt('x @'), '1:3');
1085
+ },
1086
+ () => {
1087
+ // line as well as column, once newlines have been consumed
1088
+ assertEq(errorAt('a\nb\n@'), '3:1');
1089
+ assertEq(errorAt('x\n\n @y'), '3:3');
1090
+ },
1091
+ () => {
1092
+ // a number poisoned by a trailing character points at that character
1093
+ assertEq(errorAt('00'), '1:2');
1094
+ },
1095
+ () => {
1096
+ // a number cut short points just past the input
1097
+ assertEq(errorAt('1.'), '1:3');
1098
+ },
1099
+ () => {
1100
+ // Unterminated tokens anchor at the token's *start*, not where the
1101
+ // input ran out: the grammar matches them and tags them
1102
+ // 'unterminated', so this is the structural-error path, not a failed
1103
+ // match. See ./todo/error-position-range.md.
1104
+ assertEq(errorAt('"value'), '1:1');
1105
+ assertEq(errorAt('"a\nb"'), '1:1');
1106
+ },
1107
+ () => {
1108
+ // an unterminated block comment is the exception: its content is
1109
+ // consumed, so the report lands at the end of input
1110
+ assertEq(errorAt('/* c'), '1:5');
1111
+ },
1112
+ ],
1059
1113
  // DJS-level: keyword remapping and '-'-folding on top of tokenizeJs. Doesn't re-test
1060
1114
  // JS-level token shapes already covered above/elsewhere in this file.
1061
1115
  djsTokenize: [
@@ -12,7 +12,7 @@ import { stringToList } from '../../text/utf16/module.f.js';
12
12
  import { concat as pathConcat } from '../../path/module.f.js';
13
13
  import { parseFromTokens } from '../parser/module.f.js';
14
14
  import { run } from '../ast/module.f.js';
15
- import { foldStep, pure } from '../../effects/module.f.js';
15
+ import { foldStep, pure, step } from '../../effects/module.f.js';
16
16
  import { readUtf8File } from '../../effects/node/module.f.js';
17
17
  const mapDjs = context => path => {
18
18
  const res = at(path)(context.complete);
@@ -21,7 +21,7 @@ const mapDjs = context => path => {
21
21
  }
22
22
  return res.djs;
23
23
  };
24
- const parseModule = path => readUtf8File(path).step(result => {
24
+ const parseModule = path => step(readUtf8File(path), result => {
25
25
  if (result[0] === 'error') {
26
26
  return pure(error({ message: 'file not found', metadata: null }));
27
27
  }
@@ -34,8 +34,8 @@ const transpileWithImports = path => parseModuleResult => context => {
34
34
  const pathsCombine = listMap(pathConcat(dir))(parseModuleResult[1][0]);
35
35
  const pathsArray = toArray(pathsCombine);
36
36
  const contextWithStack = { ...context, stack: { first: path, tail: context.stack } };
37
- return foldStep(foldNextModuleOp)(contextWithStack)(pathsArray)
38
- .step(contextWithImports => {
37
+ const x0 = foldStep(pure(pathsArray), contextWithStack, foldNextModuleOp);
38
+ return step(x0, contextWithImports => {
39
39
  if (contextWithImports.error !== null) {
40
40
  return pure(contextWithImports);
41
41
  }
@@ -60,7 +60,7 @@ const foldNextModuleOp = path => context => {
60
60
  if (at(path)(context.complete) !== null) {
61
61
  return pure(context);
62
62
  }
63
- return parseModule(path).step(parseModuleResult => transpileWithImports(path)(parseModuleResult)(context));
63
+ return step(parseModule(path), parseModuleResult => transpileWithImports(path)(parseModuleResult)(context));
64
64
  };
65
65
  /**
66
66
  * Transpiles a DJS module graph rooted at `path` into a single `Unknown` value.
@@ -69,7 +69,7 @@ const foldNextModuleOp = path => context => {
69
69
  * evaluates the AST. Returns `['ok', value]` on success, or `['error', ParseError]`
70
70
  * on a parse failure or circular dependency.
71
71
  */
72
- export const transpile = path => foldNextModuleOp(path)({ stack: null, complete: null, error: null }).step((context) => {
72
+ export const transpile = path => step(foldNextModuleOp(path)({ stack: null, complete: null, error: null }), (context) => {
73
73
  if (context.error !== null) {
74
74
  return pure(error(context.error));
75
75
  }
@@ -0,0 +1,72 @@
1
+ import { type Effect, type Operation } from '../module.f.ts';
2
+ /**
3
+ * A fluent, method-chaining monad over a raw {@link Effect} that also
4
+ * accumulates the history of every value the chain has produced. `.step(f)`
5
+ * is bind — `f` receives the current value followed by every prior value,
6
+ * most recent first (`f(t, ...p)`), and returns a raw `Effect`; `.step`
7
+ * re-wraps the result together with that history so `.step(f).step(g)`
8
+ * chains and stays in the `Eff` world throughout. `.map(f)` is the functor
9
+ * map — the same thing for an `f` that returns a plain value rather than an
10
+ * effect, so it is exactly `.step((...tp) => pure(f(...tp)))`. `P` is the
11
+ * tuple of prior values available to the *next* `.step` call; it grows by one
12
+ * element (the current `T`) on every step, starting empty at {@link eff}.
13
+ * `.value` is the exit back to a raw `Effect`, discarding the history. An
14
+ * `Eff` is not assignable to `Effect`; unwrap through `.value`.
15
+ *
16
+ * **`.map` grows the history just as `.step` does, and does not widen `O`.**
17
+ * Both follow from it being that `.step` call and nothing else: a chain
18
+ * rewritten from `.step(v => pure(f(v)))` to `.map(f)` must hand later
19
+ * callbacks the same prior values it did before, and a projection performs no
20
+ * command, so it contributes no operation for a runner to interpret.
21
+ *
22
+ * **The history is positional, so every parameter a callback declares is
23
+ * meaningful.** `f` is applied as `f(...tp)`, so a callback written
24
+ * `(v, n = 1) => …` or `(v, ...rest) => …` receives prior chain values in `n` /
25
+ * `rest` rather than the default or an empty rest — and where the types line up,
26
+ * TypeScript will not object. Declare exactly as many parameters as the callback
27
+ * intends to read; a defaulted or rest parameter after the current value is a
28
+ * bug, not a convenience. This is what makes `.map(g)` a *different* call from
29
+ * `.step(v => pure(g(v)))` whenever `g` is not genuinely unary — the lambda
30
+ * pins the arity at one, while passing `g` point-free exposes it to the prior
31
+ * values, the way `['1', '2', '3'].map(parseInt)` does.
32
+ *
33
+ * **`.value` is always an already-built `Effect`.** Reading it composes
34
+ * nothing: the projection that drops the history tuple to its current value is
35
+ * performed by the `.step` that produced the link, not deferred to the read.
36
+ * An `Eff` is a record to look into, not an object with a method that quietly
37
+ * does work when called.
38
+ *
39
+ * That costs one projection per link, paid whether or not the link is ever
40
+ * unwrapped — an n-link chain builds n of them where a deferred `.result()`
41
+ * method would build one. It is a constant factor on construction, with no
42
+ * extra forcing of the wrapped effect and no change in growth rate, bought in
43
+ * exchange for a uniform rule at the boundary every caller touches.
44
+ *
45
+ * At the entry it costs nothing at all: `eff(e).value` **is** `e`, because
46
+ * {@link eff} stores what it was handed rather than rebuilding it from the
47
+ * history, so wrapping and unwrapping round-trip to identity. `h` is still a
48
+ * thunk, so `eff(e)` composes nothing and never forces `e`: an `Eff` that is
49
+ * built and only read does no work at all.
50
+ *
51
+ * **`P` has no default, on purpose.** A default of `readonly[]` would make
52
+ * `Eff<O, T>` a spelling that silently erases history: an
53
+ * `Eff<O, T, readonly[A]>` is assignable to it, because `f` sits in a
54
+ * contravariant position and TypeScript accepts a callback declaring fewer
55
+ * parameters than the type it is checked against. The next `.step` callback
56
+ * would then be typed as receiving no prior values while the runtime still
57
+ * passes them, and any callback destructuring a rest parameter would be handed
58
+ * entries its type says cannot exist. Requiring the third argument means that
59
+ * erasure cannot be written at all, rather than merely being discouraged;
60
+ * {@link eff} spells `readonly[]` itself.
61
+ */
62
+ export type Eff<O extends Operation, T, P extends readonly unknown[]> = {
63
+ readonly value: Effect<O, T>;
64
+ readonly step: <Q extends Operation, R>(f: (...tp: readonly [T, ...P]) => Effect<Q, R>) => Eff<O | Q, R, readonly [T, ...P]>;
65
+ readonly map: <R>(f: (...tp: readonly [T, ...P]) => R) => Eff<O, R, readonly [T, ...P]>;
66
+ };
67
+ /**
68
+ * Wraps a raw {@link Effect}; the bridge into the `Eff` world, with an empty
69
+ * history. The empty tuple is spelled out because {@link Eff} deliberately has
70
+ * no default for `P` — see its docs.
71
+ */
72
+ export declare const eff: <O extends Operation, T>(value: Effect<O, T>) => Eff<O, T, readonly []>;
@@ -0,0 +1,46 @@
1
+ import { history, historyStep, mapStep, pure } from '../module.f.js';
2
+ /**
3
+ * Builds an `Eff` from two views of the same chain: `value`, the effect for the
4
+ * current value alone, and `h`, a thunk for the `[current, ...history]` tuple.
5
+ *
6
+ * **The two must denote the same computation** — `value` has to be what `h()`
7
+ * produces with the history dropped. Nothing enforces it. The
8
+ * redundancy is deliberate: `value` used to be derived from `h` on demand,
9
+ * which made disagreement impossible but also forced the entry case to rebuild
10
+ * an effect it was already holding. Passing it in is what lets {@link eff} hand
11
+ * the original back.
12
+ *
13
+ * The asymmetry between the two — one built, one deferred — is the point.
14
+ * `value` is either already in hand ({@link eff} was given it) or already built
15
+ * (`.step` has just composed the chain it projects from), so storing it costs
16
+ * no more than the projection itself. `h` is different: nothing needs the
17
+ * history tuple until a later `.step` asks for it, and composing effects is
18
+ * eager, so holding a thunk is the only way to not compose it yet. That keeps
19
+ * `eff(e)` free of work entirely.
20
+ *
21
+ * `.step` calls `h()` once and closes over the effect, so everything built
22
+ * from that link shares it. `eff`'s thunk is not memoized, so calling `.step`
23
+ * twice on the same `eff(e)` rebuilds and re-forces `e` — harmless under
24
+ * `Pure`'s contract, which requires the thunk to be pure and to tolerate
25
+ * repeat calls.
26
+ */
27
+ const create = (value, h) => {
28
+ // `self` is named so `.map` can be *defined* as the `.step` call it is
29
+ // documented to equal, rather than as a second copy of `.step`'s body that
30
+ // has to be re-checked against it.
31
+ const self = {
32
+ value,
33
+ step: f => {
34
+ const x1 = historyStep(h(), f);
35
+ return create(mapStep(x1, ([t]) => t), () => x1);
36
+ },
37
+ map: f => self.step((...tp) => pure(f(...tp)))
38
+ };
39
+ return self;
40
+ };
41
+ /**
42
+ * Wraps a raw {@link Effect}; the bridge into the `Eff` world, with an empty
43
+ * history. The empty tuple is spelled out because {@link Eff} deliberately has
44
+ * no default for `P` — see its docs.
45
+ */
46
+ export const eff = (value) => create(value, () => history(value));
@@ -0,0 +1,11 @@
1
+ export declare const proof: {
2
+ value: () => void;
3
+ pure: () => void;
4
+ chain: () => void;
5
+ overDo: () => void;
6
+ map: {
7
+ chain: () => void;
8
+ growsHistory: () => void;
9
+ overDo: () => void;
10
+ };
11
+ };
@@ -0,0 +1,58 @@
1
+ import { do_, match, pure } from '../module.f.js';
2
+ import { assert, assertEq } from '../../asserts/module.f.js';
3
+ import { assertPure } from '../proof.f.js';
4
+ import { eff } from './module.f.js';
5
+ const next = match({ add: (a, b) => a + b });
6
+ export const proof = {
7
+ value: () => {
8
+ assertPure(eff(pure(5)).value, 5);
9
+ },
10
+ pure: () => {
11
+ assertPure(pure(5), 5);
12
+ },
13
+ chain: () => {
14
+ const x = eff(pure(5))
15
+ .step(v => pure(v + 1))
16
+ .step(v => pure(v * 2))
17
+ .value;
18
+ assertPure(x, 12);
19
+ },
20
+ overDo: () => {
21
+ const e = eff(do_('add')(2, 3))
22
+ .step(r => pure(r + 1))
23
+ .value;
24
+ const r = next(e);
25
+ assert(r[0] === 'cont', r);
26
+ assertEq(r[1], 5);
27
+ assertPure(r[2](r[1]), 6);
28
+ },
29
+ map: {
30
+ chain: () => {
31
+ const x = eff(pure(5))
32
+ .map(v => v + 1)
33
+ .map(v => v * 2)
34
+ .value;
35
+ assertPure(x, 12);
36
+ },
37
+ // `.map` grows the history exactly as `.step` does, so a callback after
38
+ // it still reaches the pre-`map` value. This is the contract that makes
39
+ // rewriting `.step(v => pure(f(v)))` into `.map(f)` a pure readability
40
+ // change rather than one that alters what later callbacks receive.
41
+ growsHistory: () => {
42
+ const x = eff(pure(5))
43
+ .map(v => v + 1)
44
+ .step((v, prev) => pure(`${prev}${v}`))
45
+ .value;
46
+ assertPure(x, '56');
47
+ },
48
+ overDo: () => {
49
+ const e = eff(do_('add')(2, 3))
50
+ .map(r => r + 1)
51
+ .value;
52
+ const r = next(e);
53
+ assert(r[0] === 'cont', r);
54
+ assertEq(r[1], 5);
55
+ assertPure(r[2](r[1]), 6);
56
+ },
57
+ },
58
+ };
@@ -7,10 +7,15 @@ export type NonEmpty<O extends Operation, T> = {
7
7
  * The payload of a `List` effect: the next cons cell, or `undefined` at
8
8
  * end-of-stream.
9
9
  *
10
- * Since `Pure<T>` is now itself a lazy thunk (`() => T`), the effect alone is the
11
- * suspension point and the cell needs no extra wrapping thunk. `Effect<O, Next<O, T>>`
12
- * is used directly in places where `List<O, T>` cannot be written as a return type
13
- * (see {@link empty}).
10
+ * A `List` suspends only where a `Do` node does. `Pure` is a thunk, but that
11
+ * thunk is a discriminator rather than a suspension, and {@link nonEmpty} takes
12
+ * `tail` as an ordinary argument already evaluated by the time the cell is
13
+ * built. A chain of pure cells is therefore constructed in full, up front;
14
+ * streaming comes from cells produced inside a command's continuation, where
15
+ * the tail is not reached until a runner performs the command.
16
+ *
17
+ * `Effect<O, Next<O, T>>` is used directly in places where `List<O, T>` cannot
18
+ * be written as a return type (see {@link empty}).
14
19
  */
15
20
  export type Next<O extends Operation, T> = NonEmpty<O, T> | undefined;
16
21
  export type List<O extends Operation, T> = Effect<O, Next<O, T>>;
@@ -26,6 +31,7 @@ export type List<O extends Operation, T> = Effect<O, Next<O, T>>;
26
31
  */
27
32
  export declare const empty: <O extends Operation, T>() => Effect<O, Next<O, T>>;
28
33
  /**
29
- * Prepends `head` to a `ListEffect` `tail`, as a pure cons cell. See {@link empty}.
34
+ * Prepends `first` to a {@link List} `tail`, as a pure cons cell. `tail` is an
35
+ * ordinary argument, so it is built before the cell is — see {@link Next}.
30
36
  */
31
37
  export declare const nonEmpty: <O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>;
@@ -11,6 +11,7 @@ import { pure } from "../module.f.js";
11
11
  */
12
12
  export const empty = () => pure(undefined);
13
13
  /**
14
- * Prepends `head` to a `ListEffect` `tail`, as a pure cons cell. See {@link empty}.
14
+ * Prepends `first` to a {@link List} `tail`, as a pure cons cell. `tail` is an
15
+ * ordinary argument, so it is built before the cell is — see {@link Next}.
15
16
  */
16
17
  export const nonEmpty = (first, tail) => pure({ first, tail });
@@ -1,6 +1,6 @@
1
1
  import { assert, assertEq } from '../../asserts/module.f.js';
2
2
  import { run } from '../mock/module.f.js';
3
- import { pure } from '../module.f.js';
3
+ import { pure, step } from '../module.f.js';
4
4
  import { asBase, asNominal, create, read, write, } from './module.f.js';
5
5
  const initial = { next: 0, values: {} };
6
6
  const mock = {
@@ -22,7 +22,10 @@ const mock = {
22
22
  }, undefined];
23
23
  },
24
24
  };
25
- const program = create(1).step(key => read(key).step(value => write(key, value + 41).step(() => read(key))));
25
+ const program = step(create(1), key => {
26
+ const x = step(read(key), value => write(key, value + 41));
27
+ return step(x, () => read(key));
28
+ });
26
29
  export const proof = {
27
30
  roundTrip: () => {
28
31
  const [state, result] = run(mock)(initial)(program);
@@ -30,10 +33,7 @@ export const proof = {
30
33
  assertEq(state.values.k0, 42, state);
31
34
  },
32
35
  allocatesFreshKeys: () => {
33
- const effect = create('a').step(a => create('b').step(b => pure([
34
- asBase(a),
35
- asBase(b),
36
- ])));
36
+ const effect = step(create('a'), a => step(create('b'), b => pure([asBase(a), asBase(b)])));
37
37
  const [state, [a, b]] = run(mock)(initial)(effect);
38
38
  assertEq(a, 'k0');
39
39
  assertEq(b, 'k1');
@@ -41,8 +41,7 @@ export const proof = {
41
41
  assertEq(state.values.k1, 'b', state);
42
42
  },
43
43
  typeTest: () => {
44
- // const e = create(1).step(k => write(k, 'bad').step(() => read(k)))
45
- create(1).step(k => write(k, 5).step(() => read(k)));
44
+ step(create(1), k => step(write(k, 5), () => read(k)));
46
45
  },
47
46
  throw: () => {
48
47
  const key = asNominal('missing');