@procedures/json 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# @procedures/json
+
+## 0.3.0
+
+### Minor Changes
+
+- a6b01a9: The new package `@procedures/json` (roadmap R39) has seven pure procedures (`PURE_EFFECTS`): `json.query` (a JSON Pointer or a path query), `json.patch` (RFC 6902), `json.diff` (it gives an RFC 6902 patch), `json.merge` (RFC 7386), `json.validate` (a subset of JSON Schema, with the keywords that the check does not examine in `unchecked`), `yaml.parse` and `yaml.stringify`.
+  
+  A pointer, a path, a patch and a merge patch cannot name `__proto__`, `constructor` or `prototype`. A key `__proto__` in the data stays data. The YAML text of `yaml.stringify` is YAML 1.2 that a YAML 1.1 reader reads as the same value. Property tests examine that a patch from `json.diff` gives the second value, and that `yaml.parse` of the text of `yaml.stringify` gives the value again.
+
+### Patch Changes
+
+- Updated dependencies [ddea529]
+- Updated dependencies [b2a3e3a]
+- Updated dependencies [a8c47f1]
+- Updated dependencies [381ce3a]
+- Updated dependencies [0c627f8]
+- Updated dependencies [ae7f05f]
+- Updated dependencies [7873940]
+- Updated dependencies [29a7b29]
+- Updated dependencies [9bc2ddb]
+- Updated dependencies [a70d445]
+- Updated dependencies [bc70357]
+- Updated dependencies [07cc998]
+- Updated dependencies [a6b01a9]
+- Updated dependencies [c799cdd]
+- Updated dependencies [540f8d9]
+- Updated dependencies [b6daaec]
+- Updated dependencies [5b9264e]
+- Updated dependencies [956e88b]
+- Updated dependencies [ff62281]
+- Updated dependencies [d81d0ed]
+- Updated dependencies [f5ed492]
+- Updated dependencies [aa67cc7]
+- Updated dependencies [061fa22]
+- Updated dependencies [cfb9d69]
+- Updated dependencies [43f7de5]
+- Updated dependencies [b07bb50]
+- Updated dependencies [4a3bfa1]
+- Updated dependencies [bd0b626]
+- Updated dependencies [a6be873]
+- Updated dependencies [fb30718]
+- Updated dependencies [c5528e4]
+- Updated dependencies [fee5d9c]
+- Updated dependencies [21f7743]
+- Updated dependencies [31a0b46]
+  - @procedures/client@0.3.0
+  - @procedures/compiler@0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @procedures/json
 
-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.
+[![npm](https://img.shields.io/npm/v/@procedures/json?color=2346c4&label=npm)](https://www.npmjs.com/package/@procedures/json)
+
+```sh
+npm install @procedures/json
+```
+
+Transforms of JSON values as procedures: a query, a patch, a diff, a merge, a schema check, and YAML to JSON and back. Each procedure is pure. Its output comes only from its input, and it changes nothing.
+
+## The procedures
+
+| Procedure | What it does |
+|---|---|
+| `json.query` | It gives the values at a JSON Pointer (RFC 6901) or at a path query. |
+| `json.patch` | It applies a JSON Patch (RFC 6902). |
+| `json.diff` | It gives the JSON Patch that changes one value into another value. |
+| `json.merge` | It applies a JSON merge patch (RFC 7386). |
+| `json.validate` | It examines a value against a JSON Schema. |
+| `yaml.parse` | It parses YAML text into a JSON value. |
+| `yaml.stringify` | It writes a JSON value as YAML text. |
+
+Each procedure declares `PURE_EFFECTS`, so a read-only host can start it.
+
+```ts
+import "@procedures/json/register";
+
+await client.call(["json", "query"], { value: config, path: "services[*].image" });
+await client.call(["json", "patch"], { value: config, patch: [{ op: "replace", path: "/version", value: 2 }] });
+await client.call(["yaml", "parse"], { text: "name: app\nports: [80, 443]" });
+```
+
+## Pointers and paths
+
+`json.query` takes `pointer` or `path`. Each match has its JSON Pointer.
+
+| Path | Meaning |
+|---|---|
+| `$` | The whole value. It is optional at the start. |
+| `.name` or `name` | A member of an object. A name has letters, digits, `_`, `$` and `-`. |
+| `["a.b"]` | A member with any key. A backslash escapes a quote or a backslash. |
+| `[2]`, `[-1]` | An item of an array. `[-1]` is the last item. |
+| `*` or `[*]` | Each member or each item. |
+| `..name` | The same step at each depth. |
+
+The path query has no filters and no scripts.
+
+## The prototype keys
+
+A pointer, a path, a JSON Patch and a merge patch cannot name `__proto__`, `constructor` or `prototype`. The error has the code `PROTOTYPE_KEY`.
+
+- A key `__proto__` in the data stays data. Each object that a procedure makes has own data properties only.
+- The patch of `json.diff` does not name a prototype key. When a difference is under such a key, the patch replaces the object that holds the key.
+
+## Patches
+
+- `json.patch` applies all operations or none. A failed `test` operation gives the code `TEST_FAILED`.
+- `json.diff` keeps the shared start and end of an array, so an insert at the start is one `add`.
+- `json.patch` of the output of `json.diff` on the first value gives the second value. A property test with random JSON values examines this rule.
+- `json.merge` removes a key whose patch value is null. A patch that is not an object replaces the value.
+
+## The schema check
+
+`json.validate` uses the validator of [`@procedures/compiler`](../compiler), the validator that `program.check` uses. It examines a subset of JSON Schema:
+
+- `type`, `enum`, `const` and `$ref` to the same schema
+- `allOf`, `anyOf` and `oneOf`. The check examines `oneOf` as `anyOf`, so a value that agrees with two branches passes.
+- `properties`, `required`, `additionalProperties` and `patternProperties`
+- `items`, `prefixItems`, `additionalItems`, `minItems` and `maxItems`
+- `minLength`, `maxLength` and `pattern`. The lengths count UTF-16 code units.
+- `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum` and `multipleOf`
+
+The check ignores `format` and the other annotations, as the standard tells. The output field `unchecked` lists each keyword of the schema that the check does not examine. Examples are `not`, `if`, `uniqueItems`, `minProperties` and a `$ref` to another document. When `unchecked` is empty, the verdict is complete. A `oneOf` in the schema goes into `unchecked` too, because its check is not complete.
+
+## YAML
+
+- The parse uses YAML 1.2 with the core schema of the [`yaml`](https://www.npmjs.com/package/yaml) package.
+- The parse gives only JSON values. `.inf` and `.nan` are errors. A map or a list as a key is an error.
+- A key that is a number, a boolean or null becomes its text.
+- The explicit YAML 1.1 tags (`!!binary`, `!!timestamp`) give their text.
+- The parse refuses more than 100 aliases, because many aliases can fill the memory. It also refuses a duplicate key.
+- `all: true` reads more than one document and gives the list of documents.
+- The text of `yaml.stringify` is YAML 1.2, and a YAML 1.1 reader reads the same value. A string that YAML 1.1 reads as another type is in double quotes, for example `yes`, `no`, `on`, a date or `0777`.
+- `yaml.parse` of the text of `yaml.stringify` gives the value again. A property test with random JSON values examines this rule.
+- A strict YAML 1.1 reader reads a number with an exponent and without a fraction as a string, for example `1e+21`.
+
+## Errors
+
+Each error is a `JsonError`. A server sends it with the code `HANDLER_ERROR` and the message. The field `code` tells the kind:
+
+| Code | Cause |
+|---|---|
+| `NOT_JSON` | A value is not JSON: `undefined`, `NaN`, a date or a value that refers to itself. The message has the pointer of the value. |
+| `INVALID_POINTER` | A pointer or a path is not correct. |
+| `PROTOTYPE_KEY` | A pointer, a path or a patch names a prototype key. |
+| `INVALID_PATCH` | An operation is not correct, or its location does not exist. |
+| `TEST_FAILED` | A `test` operation found another value. |
+| `INVALID_YAML` | The YAML text is not correct, or it has a value that JSON does not have. |
+| `INVALID_SCHEMA` | The schema is not an object or a boolean. |
+
+## Related packages
+
+- [`@procedures/client`](../client): the core, with `PURE_EFFECTS`.
+- [`@procedures/compiler`](../compiler): the validator of the schema check.
+- [`@procedures/http`](../http): the HTTP procedures.