sendscript 2.3.1 → 2.3.3

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "proseWrap": "always",
+  "printWidth": 80,
+  "semi": false,
+  "singleQuote": true
+}

package/CHANGELOG.md

@@ -4,8 +4,24 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v2.3.3](https://github.com/bas080/sendscript/compare/v2.3.2...v2.3.3)
+
+- Add JSDoc to relevant function for docs [`d1d3709`](https://github.com/bas080/sendscript/commit/d1d3709088a51b71651170ef642b013eedc9ca3a)
+- Remove tests section from README [`5da7bb3`](https://github.com/bas080/sendscript/commit/5da7bb3f3b1dc8078683e076fe2b520bc6d28896)
+- Add generated from JSDoc reference section [`08eb266`](https://github.com/bas080/sendscript/commit/08eb266b06d8998e6849dbc5c9738fbe782ada18)
+
+#### [v2.3.2](https://github.com/bas080/sendscript/compare/v2.3.1...v2.3.2)
+
+> 14 April 2026
+
+- Format the README.mz file [`df43dbb`](https://github.com/bas080/sendscript/commit/df43dbb8b790cfc612536f49571f9fe4aad03837)
+- Move some commands from README to CONTRIBUTING [`45659c5`](https://github.com/bas080/sendscript/commit/45659c51354ac3bbe3bed5ef3826785d8a1a4a32)
+- Add format markdown check in contributing md [`e68d4d6`](https://github.com/bas080/sendscript/commit/e68d4d6aea26a7a54c2f933ad98a8e363d7f3357)
+
 #### [v2.3.1](https://github.com/bas080/sendscript/compare/v2.3.0...v2.3.1)
 
+> 14 April 2026
+
 - Update typedoc dev dep to 0.28.19 [`69e8cc4`](https://github.com/bas080/sendscript/commit/69e8cc48251af650c02faf3214ff0f9c2b61dbc9)
 
 #### [v2.3.0](https://github.com/bas080/sendscript/compare/v2.2.0...v2.3.0)

package/CONTRIBUTING.md

@@ -1,16 +1,38 @@
 # Contributing
 
-
 For the README.mz examples to work we need sendscript to be linked.
 
 ```bash bash > /dev/null
 set -e
 
+npm ci
 npm link
 npm link sendscript
 cd ./example
-npm ci
-npm link sendscript
+```
+
+Check if packages are up to date on release.
+
+```bash bash
+npm outdated && echo 'No outdated packages found'
+```
+
+Check if no vulnerable dependencies
+
+```bash bash
+npm audit
+```
+
+Check if code follows standard formatting.
+
+```bash bash
+npx standard
+```
+
+Check if markdown is correctly formatted.
+
+```bash bash
+npx prettier --check --parser markdown ./README.mz ./CONTRIBUTING.md
 ```
 
 Generate the README from the mz file.
@@ -18,7 +40,9 @@ Generate the README from the mz file.
 ```bash bash
 markatzea ./README.mz | tee ./README.md
 
-npx markdown-toc -i README.md
+npx documentation readme references.mjs parse.mjs stringify.mjs -s Reference --github --a public --markdown-toc false
+
+npx markdown-toc --maxdepth 3 -i README.md
 
 git add *.md ./example
 ```

package/README.md

@@ -2,14 +2,22 @@
 
 Write JS code that you can run on servers, browsers or other clients.
 
-[![NPM](https://img.shields.io/npm/v/sendscript?color=blue&style=flat-square)](https://www.npmjs.com/package/sendscript)
+[![NPM](https://img.shields.io/npm/v/sendscript?color=blue\&style=flat-square)](https://www.npmjs.com/package/sendscript)
 [![100% Code Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square)](#tests)
 [![Standard Code Style](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](https://standardjs.com)
-[![License](https://img.shields.io/npm/l/sendscript?color=brightgreen&style=flat-square)](./LICENSE.txt)
+[![License](https://img.shields.io/npm/l/sendscript?color=brightgreen\&style=flat-square)](./LICENSE.txt)
 
 <!-- toc -->
 
 - [Introduction](#introduction)
+- [Reference](#reference)
+  * [defaultLeafDeserializer](#defaultleafdeserializer)
+  * [Parse](#parse)
+  * [parse](#parse)
+  * [References](#references)
+  * [strictStringify](#strictstringify)
+  * [Stringify](#stringify)
+  * [stringify](#stringify)
 - [Socket example](#socket-example)
   * [Module](#module)
   * [Server](#server)
@@ -25,34 +33,33 @@ Write JS code that you can run on servers, browsers or other clients.
   * [Validating structured input](#validating-structured-input)
 - [Leaf Serializer](#leaf-serializer)
   * [Example with superjson](#example-with-superjson)
-- [Tests](#tests)
-- [Formatting](#formatting)
 - [Changelog](#changelog)
-- [Dependencies](#dependencies)
 - [License](#license)
-- [Roadmap](#roadmap)
+- [Issues](#issues)
 
 <!-- tocstop -->
 
 ## Introduction
 
-There has been interest in improving APIs by allowing aggregations in a
-single request. Examples include
+There has been interest in improving APIs by allowing aggregations in a single
+request. Examples include
 
-- [JSON-RPC](https://json-rpc.dev/) which allows you to do multiple requests
-  but it does not allow you to compose the return value of one endpoint to be the
-  input/arguments of another.
+*   [JSON-RPC](https://json-rpc.dev/) which allows you to do multiple requests but
+    it does not allow you to compose the return value of one endpoint to be the
+    input/arguments of another.
 
-- [GraphQL](https://graphql.org/) is very cool but also introduces a new languages and the
-  tooling that is required to wield it.
+*   [GraphQL](https://graphql.org/) is very cool but also introduces a new
+    languages and the tooling that is required to wield it.
 
-What SendScript attempts is to allow for very expressive queries and mutations to be performed
-that read and write like ordinary JS. That means that the queries and complete programs
-that are sent to the server from a client can also just run on the server as is. The only
-limitation being the serialization which by default is limited by JSON and could be extended by
-using more advanced (de)serialization libraries.
+What SendScript attempts is to allow for very expressive queries and mutations
+to be performed that read and write like ordinary JS. That means that the
+queries and complete programs that are sent to the server from a client can also
+just run on the server as is. The only limitation being the serialization which
+by default is limited by JSON and could be extended by using more advanced
+(de)serialization libraries.
 
-SendScript produces an intermediate JSON representation of the program. Let's see what that looks like.
+SendScript produces an intermediate JSON representation of the program. Let's
+see what that looks like.
 
 ```js
 import Stringify from 'sendscript/stringify.mjs'
@@ -63,6 +70,7 @@ const stringify = Stringify()
 
 console.log(stringify(add(1,2)))
 ```
+
 ```json
 ["call",["ref","add"],[["leaf","1"],["leaf","2"]]]
 ```
@@ -84,6 +92,7 @@ const program = '["call",["ref","add"],[1,2]]'
 
 console.log(parse(program))
 ```
+
 ```json
 3
 ```
@@ -91,22 +100,113 @@ console.log(parse(program))
 SendScript does more than a simple function call. It supports function
 composition and even await.
 
-This package is nothing more than the absolute core of sendscript. It
-includes:
+This package is nothing more than the absolute core of sendscript. It includes:
+
+*   The `references` function to create stubs to write the programs.
+*   `stringify` which takes the program and returns a JSON string.
+*   `parse` which takes the `stringify` JSON string and a real module and returns
+    the result.
+
+The naming could use more love and there are many things to solve either in the
+core or around it. Things like supporting more complex (de)serializers, errors
+and maybe mixing client functions with sendscript programs. Contact me if I have
+piqued your interest.
+
+***
+
+SendScript leaves it up to you to choose HTTP, web-sockets or any other method
+of communication between servers and clients that best fits your needs.
+
+## Reference
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### defaultLeafDeserializer
+
+Default deserializer for leaf nodes.
+
+#### Parameters
+
+*   `text` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
+
+Returns **any**&#x20;
+
+### Parse
+
+Creates a program parser for a given schema and environment.
+
+The parser:
+
+*   resolves references into runtime functions
+*   deserializes leaf nodes
+*   collects and executes async awaits
+*   evaluates AST-like JSON programs
+
+#### Parameters
+
+*   `schemaArg` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | \[[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)])>**&#x20;
+*   `env` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** runtime environment for refs
+*   `deserialize`   (optional, default `defaultLeafDeserializer`)
+
+### parse
+
+Parses and executes a serialized program.
+
+#### Parameters
+
+*   `program` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** JSON encoded program
+
+Returns **(any | [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<any>)**&#x20;
+
+### References
+
+Builds a nested API structure from a schema definition.
+
+Schema supports:
+
+*   string => leaf function node
+*   \[name, children] => namespace with nested schema
+
+#### Parameters
+
+*   `schema` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | \[[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)])>**&#x20;
+*   `parentPath` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>**  (optional, default `[]`)
+
+<!---->
+
+*   Throws **[Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)** If schema format is invalid
+
+Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Nested instrumented API object
+
+### strictStringify
+
+Default strict serializer for leaf values.
+
+Rejects non-JSON-safe values.
+
+#### Parameters
+
+*   `x` **any**&#x20;
+
+Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
 
-- The `references` function to create stubs to write the programs.
-- `stringify` which takes the program and returns a JSON string.
-- `parse` which takes the `stringify` JSON string and a real module and returns the result.
+### Stringify
 
-The naming could use more love and there are many things to solve either in the core or around it.
-Things like supporting more complex (de)serializers, errors and maybe mixing client functions with
-sendscript programs. Contact me if I have piqued your interest.
+Creates a stringify function for SendScript AST structures.
 
----
+#### Parameters
 
-SendScript leaves it up to you to choose HTTP, web-sockets or any other
-method of communication between servers and clients that best fits your
-needs.
+*   `leafSerializer`   (optional, default `strictStringify`)
+
+### stringify
+
+Serializes a program into a JSON string representation.
+
+#### Parameters
+
+*   `program` **any**&#x20;
+
+Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
 
 ## Socket example
 
@@ -120,7 +220,7 @@ We write a simple module.
 // ./example/math.mjs
 
 export const add = (a, b) => a + b
-export const square = a => a * a
+export const square = (a) => a * a
 ```
 
 ### Server
@@ -172,12 +272,10 @@ const stringify = Stringify()
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
 
-const send = program => {
+const send = (program) => {
   return new Promise((resolve, reject) => {
     client.emit('message', stringify(program), (error, result) => {
-      error
-        ? reject(error)
-        : resolve(result)
+      error ? reject(error) : resolve(result)
     })
   })
 }
@@ -207,15 +305,16 @@ node ./example/client.socket.io.mjs
 
 pkill sendscript
 ```
-```
-Result:  100
-```
+
+    Result:  100
 
 ## Repl
 
-Sendscript ships with a barebones (no-dependencies) node-repl script. One can run it by simply typing `sendscript` in their console.
+Sendscript ships with a barebones (no-dependencies) node-repl script. One can
+run it by simply typing `sendscript` in their console.
 
-> Use the `DEBUG='*'` to enable all logs or `DEBUG='sendscript:*'` for printingonly sendscript logs.
+> Use the `DEBUG='*'` to enable all logs or `DEBUG='sendscript:*'` for
+> printingonly sendscript logs.
 
 ## Promises
 
@@ -227,44 +326,51 @@ Supported since vs `v2.3`.
 const getOrCreatePost = send(createPost(title).catch(createPost(title)))
 ```
 
-You will likely need to define better helpers that makes it safer to handle rejections and work with promises. It is however sensible to have
-this basic behavior for the sendscript DSL and parser.
+You will likely need to define better helpers that makes it safer to handle
+rejections and work with promises. It is however sensible to have this basic
+behavior for the sendscript DSL and parser.
 
 ### await
 
-SendScript supports async/await seamlessly within a single request. This avoids the performance pitfalls of waterfall-style messaging, which can be especially slow on high-latency networks.
+SendScript supports async/await seamlessly within a single request. This avoids
+the performance pitfalls of waterfall-style messaging, which can be especially
+slow on high-latency networks.
 
-While it's possible to chain promises manually or use utility functions, native async/await support makes your code more readable, modern, and easier to reason about — aligning SendScript with today’s JavaScript best practices.
+While it's possible to chain promises manually or use utility functions, native
+async/await support makes your code more readable, modern, and easier to reason
+about — aligning SendScript with today’s JavaScript best practices.
 
 ```js
 const userId = 'user-123'
 const program = {
   unread: await fetchUnreadMessages(userId),
   emptyTrash: await emptyTrash(userId),
-  archived: await archiveMessages(selectMessages({ old: true }))
+  archived: await archiveMessages(selectMessages({ old: true })),
 }
 
 const result = await send(program)
 ```
 
-This operation is done in a single round-trip. The result is an object with the defined properties and returned values.
+This operation is done in a single round-trip. The result is an object with the
+defined properties and returned values.
 
 ## TypeScript
 
 There is a good use-case to write a module in TypeScript.
 
-1. Obviously the module would have the benefits that TypeScript offers when
-   coding.
-2. You can use tools like [typedoc][typedoc] to generate docs from your types to
-   share with consumers of your API.
-3. You can use the types of the module to coerce your client to adopt the
-   module's type.
+1.  Obviously the module would have the benefits that TypeScript offers when
+    coding.
+2.  You can use tools like [typedoc][typedoc] to generate docs from your types to
+    share with consumers of your API.
+3.  You can use the types of the module to coerce your client to adopt the
+    module's type.
 
 Let's say we have this module which we use on the server.
 
 ```bash
 cat ./example/typescript/math.ts
 ```
+
 ```ts
 export const add = (a: number, b: number) => a + b
 export const square = (a: number) => a * a
@@ -275,6 +381,7 @@ We can then coerce the types of the instrumented stubs.
 ```bash
 cat ./example/typescript/client.ts
 ```
+
 ```ts
 import math  from './math.client.ts'
 import Stringify from 'sendscript/stringify.mjs'
@@ -300,15 +407,16 @@ npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./e
 
 You can see the docs [here](./example/typescript/docs/globals.md)
 
-> [!NOTE]
-> Although type coercion on the client side can improve the development
-> experience, it does not represent the actual type.
-> Values are subject to serialization and deserialization.
-
+> \[!NOTE] Although type coercion on the client side can improve the development
+> experience, it does not represent the actual type. Values are subject to
+> serialization and deserialization.
 
 ## Schema and Nested Modules
 
-Sendscript allows you to define your API as a **nested object of functions**, making it easy to organize your DSL into modules and submodules. Each function is instrumented so that when serialized, it produces a structured reference that can be safely sent and executed elsewhere.
+Sendscript allows you to define your API as a **nested object of functions**,
+making it easy to organize your DSL into modules and submodules. Each function
+is instrumented so that when serialized, it produces a structured reference that
+can be safely sent and executed elsewhere.
 
 ### Defining a Nested Module
 
@@ -340,17 +448,13 @@ Functions are referenced via their **path in the module tree**:
 ```js
 const { math, vector } = references(schema)
 
-math.add(
-  1,
-  vector.length(
-    vector.multiply([1,2], 3)
-  )
-)
+math.add(1, vector.length(vector.multiply([1, 2], 3)))
 ```
 
 ## Validation (using Zod)
 
-SendScript focuses on program serialization and execution. For runtime input validation, you can use [Zod](https://zod.dev).
+SendScript focuses on program serialization and execution. For runtime input
+validation, you can use [Zod](https://zod.dev).
 
 ### Validating structured input
 
@@ -358,7 +462,7 @@ SendScript focuses on program serialization and execution. For runtime input val
 const userSchema = z.object({
   id: z.string().uuid(),
   name: z.string(),
-  roles: z.array(z.string())
+  roles: z.array(z.string()),
 })
 
 export function createUser(user) {
@@ -370,19 +474,25 @@ export function createUser(user) {
 
 **Benefits**:
 
-- Ensures arguments match expected types and shapes.
-- Throws structured errors that can be propagated to clients.
-- Works with TypeScript for automatic type inference.
+*   Ensures arguments match expected types and shapes.
+*   Throws structured errors that can be propagated to clients.
+*   Works with TypeScript for automatic type inference.
 
 ## Leaf Serializer
 
-By default, SendScript uses JSON for serialization, which limits support to primitives and plain objects/arrays. To support richer JavaScript types like `Date`, `RegExp`, `BigInt`, `Map`, `Set`, and `undefined`, you can provide custom serialization functions.
+By default, SendScript uses JSON for serialization, which limits support to
+primitives and plain objects/arrays. To support richer JavaScript types like
+`Date`, `RegExp`, `BigInt`, `Map`, `Set`, and `undefined`, you can provide
+custom serialization functions.
 
-The `stringify` function accepts an optional `leafSerializer` parameter, and `parse` accepts an optional `leafDeserializer` parameter. These functions control how non-SendScript values (leaves) are encoded and decoded.
+The `stringify` function accepts an optional `leafSerializer` parameter, and
+`parse` accepts an optional `leafDeserializer` parameter. These functions
+control how non-SendScript values (leaves) are encoded and decoded.
 
 ### Example with superjson
 
-Here's how to use [superjson](https://github.com/blitz-js/superjson) to support extended types:
+Here's how to use [superjson](https://github.com/blitz-js/superjson) to support
+extended types:
 
 ```js
 import SuperJSON from 'superjson'
@@ -412,7 +522,10 @@ const program = {
   pattern: /foo/gi,
   count: BigInt('9007199254740992'),
   items: new Set([1, 2, 3]),
-  mapping: new Map([['a', 1], ['b', 2]])
+  mapping: new Map([
+    ['a', 1],
+    ['b', 2],
+  ]),
 }
 
 // Serialize with custom leaf serializer
@@ -422,8 +535,8 @@ const json = stringify(processData(program))
 const env = {
   processData: (data) => ({
     success: true,
-    received: data
-  })
+    received: data,
+  }),
 }
 
 // Parse with custom leaf deserializer
@@ -432,41 +545,8 @@ const parse = Parse(schema, env, leadDeserializer)
 const result = parse(json)
 ```
 
-The leaf wrapper format is `['leaf', serializedPayload]`, making it unambiguous and safe from colliding with SendScript operators.
-
-## Tests
-
-Tests with 100% code coverage.
-
-```bash
-npm t -- -R silent
-npm t -- report text-summary
-```
-```
-
-> sendscript@2.3.1 test
-> tap -R silent
-
-
-> sendscript@2.3.1 test
-> tap report text-summary
-
-
-=============================== Coverage summary ===============================
-Statements   : 100% ( 372/372 )
-Branches     : 100% ( 137/137 )
-Functions    : 100% ( 24/24 )
-Lines        : 100% ( 372/372 )
-================================================================================
-```
-
-## Formatting
-
-Standard because no config.
-
-```bash
-npx standard
-```
+The leaf wrapper format is `['leaf', serializedPayload]`, making it unambiguous
+and safe from colliding with SendScript operators.
 
 ## Changelog
 
@@ -477,27 +557,22 @@ The [changelog][changelog] is generated using the useful
 npx auto-changelog -p
 ```
 
-## Dependencies
+## License
 
-Check if packages are up to date on release.
+See the [LICENSE.txt][license] file for details.
 
-```bash
-npm outdated && echo 'No outdated packages found'
-```
-```
-No outdated packages found
-```
+## Issues
 
-## License
+See [issues][issues] for roadmap and known bugs.
 
-See the [LICENSE.txt][license] file for details.
+[license]: ./LICENSE.txt
+
+[socket.io]: https://socket.io/
+
+[changelog]: ./CHANGELOG.md
 
-## Roadmap
+[auto-changelog]: https://www.npmjs.com/package/auto-changelog
 
-- [ ] Support for simple lambdas to compose functions more easily.
+[typedoc]: https://github.com/TypeStrong/typedoc
 
-[license]:./LICENSE.txt
-[socket.io]:https://socket.io/
-[changelog]:./CHANGELOG.md
-[auto-changelog]:https://www.npmjs.com/package/auto-changelog
-[typedoc]:https://github.com/TypeStrong/typedoc
+[issues]: https://github.com/bas080/sendscript/issues