@procedures/generators 0.0.0-stage → 0.62.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/CHANGELOG.md ADDED
@@ -0,0 +1,50 @@
1
+ # @procedures/generators
2
+
3
+ ## 0.62.0
4
+
5
+ ### Patch Changes
6
+
7
+ - b7fbc8e: A parameter that is not JSON can now get a constructed input: a pure function of the package makes its value from JSON before each call.
8
+
9
+ - The generator of `@procedures/compiler` finds the factory of the type of a parameter. A factory is a pure export with one signature that gives an object. The schema of the parameter is the input of the factory, with the new keyword `x-procedures-construct`.
10
+ - When more than one factory gives a type, the new field `constructors` of the overlay names one. Without it, the function stays exempt, and the detail names the factories.
11
+ - The loader `exportsModule()` makes a new value with the factory before each call. It throws when the package does not export the factory.
12
+ - The new exports `CONSTRUCT_KEYWORD` and `ExportsConstruct` give the keyword and its value.
13
+ - Fix: a function parameter whose result is a function now gets the exemption `function-parameter`. Before, its sub-program gave JSON where the package expected a function.
14
+ - `@procedures/generators` now has 23 procedures, for 23 of the 31 functions of `@mark1russell7/rigor-generators`. Six designs take a `Random` as the input of `random`, for example `{ "seed": 7 }`.
15
+ - The new program `latin-hypercube-from-a-label` of `wraps.programs.json` uses a constructed input.
16
+
17
+ PATCH: before 1.0.0, a backward-compatible feature and a fix raise PATCH. The new overlay field is optional, and the old manifests load without a change.
18
+ - 9efdd12: The new package `@procedures/generators` gives the functions of `@mark1russell7/rigor-generators` as procedures: seeds, hashes, canonical JSON, draws and designs. It is the second wrap package of direction 40.
19
+
20
+ - The package has 17 procedures in the namespace `generators`, for 17 of the 31 functions of `@mark1russell7/rigor-generators` 0.2.0. Each procedure has no effects. The README gives the reason for each of the other 14 functions.
21
+ - The generator of `@procedures/compiler` puts a named union into `$defs` one time. Before, a recursive union, for example `DistributionSpec` of `rigor-generators`, overflowed the stack. For an output with an `undefined` member, the schema is the definition or `null`.
22
+ - The generator fails closed on a schema deeper than 64 levels: the function gets an exemption.
23
+ - The manifest of `@procedures/statistics` now has its named unions in `$defs`. The procedures and their inputs do not change.
24
+ - A wrap with `"pure": true` in its `wrap.json` has the gate of kind 1. Its procedures have no effects, and `client.browser` lists its three entries.
25
+ - The new file `wraps.programs.json` holds programs across the pure wraps. `node scripts/wraps.ts check` starts each program two times. The check fails when a result changes, when a program calls a procedure outside the pure wraps, or when no program uses a pure wrap.
26
+
27
+ PATCH: before 1.0.0, a new package and a backward-compatible fix raise PATCH. No export changes in a way that breaks a caller.
28
+ - 870f429: Four new wraps of kind 1, made from the types of their homes, with no procedure written by hand:
29
+
30
+ - `@procedures/predicates`: 13 of 13 functions of `@mark1russell7/predicates`.
31
+ - `@procedures/quantity`: 27 of 32 functions of `@mark1russell7/quantity`. The other 5 hold a `bigint`.
32
+ - `@procedures/algebra`: 41 of 46 functions of `@mark1russell7/algebra`.
33
+ - `@procedures/optional`: 20 of 23 functions of `@mark1russell7/optional`. The other 3 are overloads.
34
+
35
+ Each wrap is pure. `wraps.programs.json` has three new programs across the libraries: the netem time of a datagram (algebra and quantity), the side of the median point of a sample (predicates and statistics), and the text of a duration that can be absent (optional and quantity).
36
+
37
+ Fixes of the generator of `@procedures/compiler`:
38
+
39
+ - The type `{}` is each JSON value but `null`, as in TypeScript. So `NonNullable<T>` is the schema of `T` without `null`. Before, the schema was an object with no properties, so the output check of `optional.fromNullable` refused a number.
40
+ - `ReadonlyMap` and `ReadonlySet` are not JSON, as `Map` and `Set`. The detail of an exemption now names the type.
41
+ - The description of a parameter has no hyphen of TSDoc. This changes 15 descriptions of `@procedures/statistics` and `@procedures/generators`.
42
+
43
+ PATCH: before 1.0.0, a backward-compatible feature and a fix raise PATCH. The new packages and procedures add to the API, and the fixed schemas take each value that the function takes.
44
+ - Updated dependencies [b7fbc8e]
45
+ - Updated dependencies [14f61a7]
46
+ - Updated dependencies [b3e65e7]
47
+ - Updated dependencies [9efdd12]
48
+ - Updated dependencies [870f429]
49
+ - @procedures/compiler@0.62.0
50
+ - @procedures/client@0.62.0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025-2026 Mark Russell
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,85 @@
1
- # Temporary Holding Version
1
+ # @procedures/generators
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/@procedures/generators?color=2346c4&label=npm)](https://www.npmjs.com/package/@procedures/generators)
4
+
5
+ The functions of [`@mark1russell7/rigor-generators`](https://www.npmjs.com/package/@mark1russell7/rigor-generators) as procedures: seeds, hashes, canonical JSON, distributions and the shrink of a failed point. Each procedure is a typed call, an MCP tool and a CLI command.
6
+
7
+ No procedure is written by hand. The generator of `@procedures/compiler` reads the types of the library and writes `src/manifest.ts`. Thus a procedure cannot drift from its function.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ pnpm add @procedures/generators @procedures/client
13
+ ```
14
+
15
+ A host registers the procedures with `createRegistry(generatorsModule)`, or with `import "@procedures/generators/register"` for the global registry. The package root and `./module` register nothing.
16
+
17
+ ## Procedures
18
+
19
+ The package has 23 procedures in the namespace `generators`, one for each function of the library with JSON inputs and a JSON output. Each procedure has no effects: it reads nothing and writes nothing.
20
+
21
+ - The input is an object with one property for each parameter of the function, by its name.
22
+ - The JSON Schemas of the input and the output come from the types. A named type, for example `DistributionSpec`, has one definition in `$defs`.
23
+ - A function parameter is a sub-program: one call of a pure procedure, as data. The `keyOf` of `stablePick` is an example.
24
+ - A parameter `r` of the type `Random` is a constructed input. Its value is the input of `random`, for example `{ "seed": 7 }`.
25
+
26
+ ## Constructed inputs
27
+
28
+ A `Random` is an object with methods, so it is not JSON. The function `random(seed)` makes it from JSON.
29
+
30
+ - Before each call, the procedure makes a new `Random` with `random(seed)`. Thus two calls with the same seed give the same value.
31
+ - The parameter `source` of `random` is a function that gives a function. A sub-program gives only JSON, so the input has no `source`.
32
+ - Two functions give a `Random`: `random` and `randomOf`. The field `overlay.constructors` of `wrap.json` names `random`.
33
+
34
+ ```ts
35
+ const output = await invokePath(["generators", "latinHypercube"], { n: 5, d: 3, r: { seed: 7 } }, { registry });
36
+ ```
37
+
38
+ `generatorsManifest` gives the names, the schemas and the effects of each procedure.
39
+
40
+ ## Example
41
+
42
+ ```ts
43
+ import { createRegistry, invokePath, outputValue } from "@procedures/client";
44
+ import { generatorsModule } from "@procedures/generators";
45
+
46
+ const registry = createRegistry(generatorsModule);
47
+ const output = await invokePath(["generators", "deriveSeed"], { seed: 7, label: "run" }, { registry });
48
+ const seed = await outputValue(output);
49
+ ```
50
+
51
+ ## The functions with no procedure
52
+
53
+ 8 functions of the library have no procedure. The manifest gives each with its reason:
54
+
55
+ | Functions | Reason | The cause |
56
+ | --- | --- | --- |
57
+ | `familyMap`, `mulberry32`, `sampler` | `output-not-json` | The result is a function. |
58
+ | `random`, `randomOf` | `function-parameter` | The parameter `source` is a function that gives a function. The result is a `Random`, a constructed input of the other procedures. |
59
+ | `distributionOf` | `output-not-json` | The result is a `Distribution`: an object with methods. |
60
+ | `coveringRows` | `output-not-json` | The type of the result is a generic mapped type. |
61
+ | `shrinkPointAsync` | `function-parameter` | The function `fails` can give a promise. |
62
+
63
+ ## Update the manifest
64
+
65
+ After an update of `@mark1russell7/rigor-generators`, start this command from the root of the repository:
66
+
67
+ ```bash
68
+ node scripts/wraps.ts generate --package generators
69
+ ```
70
+
71
+ The command writes `src/manifest.ts`. It also raises the ratchet of the library in `wraps.coverage.json`. CI starts `node scripts/wraps.ts check`. The check fails when the manifest is not current, or when the share of the functions with a procedure falls.
72
+
73
+ ## The gate of a pure wrap
74
+
75
+ The wrap is pure: its `wrap.json` has `"pure": true`. So `node scripts/wraps.ts check` also examines these conditions:
76
+
77
+ - Each procedure has no effects.
78
+ - The field `client.browser` lists `.`, `./module` and `./register`.
79
+ - A program of `wraps.programs.json` uses a procedure of the wrap.
80
+
81
+ The programs of `wraps.programs.json`, at the root of the repository, use the procedures of the pure wraps, also across libraries. The check starts each program two times. The two results must be equal, and equal to the recorded result. An update of a library can change a result on purpose. Then start `node scripts/wraps.ts generate` with no `--package`. Give the reason in the pull request.
82
+
83
+ ## License
84
+
85
+ MIT
@@ -0,0 +1,2 @@
1
+ export * from "./module.js";
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,3 @@
1
+ // The root registers nothing: import "@procedures/generators/register", or give the module to createRegistry()
2
+ export * from "./module.js";
3
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,cAAc,aAAa,CAAC"}
@@ -0,0 +1,3 @@
1
+ import type { ExportsManifest } from "@procedures/compiler";
2
+ export declare const manifest: ExportsManifest;
3
+ //# sourceMappingURL=manifest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,eAAO,MAAM,QAAQ,EAAE,eAwxDtB,CAAC"}