sendscript 2.3.2 → 2.3.3

package/CHANGELOG.md

@@ -4,8 +4,16 @@ 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)

package/CONTRIBUTING.md

@@ -40,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,10 +33,9 @@ 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)
 - [Changelog](#changelog)
 - [License](#license)
-- [Roadmap](#roadmap)
+- [Issues](#issues)
 
 <!-- tocstop -->
 
@@ -37,12 +44,12 @@ Write JS code that you can run on servers, browsers or other clients.
 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
@@ -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
 ```
@@ -93,21 +102,112 @@ composition and even await.
 
 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 `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;
+
+### Stringify
+
+Creates a stringify function for SendScript AST structures.
+
+#### Parameters
+
+*   `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
 
 For this example we'll use [socket.io][socket.io].
@@ -205,9 +305,8 @@ node ./example/client.socket.io.mjs
 
 pkill sendscript
 ```
-```
-Result:  100
-```
+
+    Result:  100
 
 ## Repl
 
@@ -259,18 +358,19 @@ defined properties and returned values.
 
 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
@@ -281,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'
@@ -306,7 +407,7 @@ 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
+> \[!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.
 
@@ -373,9 +474,9 @@ 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
 
@@ -447,32 +548,6 @@ 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.2 test
-> tap -R silent
-
-
-> sendscript@2.3.2 test
-> tap report text-summary
-
-
-=============================== Coverage summary ===============================
-Statements   : 100% ( 372/372 )
-Branches     : 100% ( 137/137 )
-Functions    : 100% ( 24/24 )
-Lines        : 100% ( 372/372 )
-================================================================================
-```
-
 ## Changelog
 
 The [changelog][changelog] is generated using the useful
@@ -486,12 +561,18 @@ npx auto-changelog -p
 
 See the [LICENSE.txt][license] file for details.
 
-## Roadmap
+## Issues
 
-- [ ] Support for simple lambdas to compose functions more easily.
+See [issues][issues] for roadmap and known bugs.
 
 [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

package/README.mz

@@ -79,6 +79,10 @@ 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
+
+<!-- Reference -->
+
 ## Socket example
 
 For this example we'll use [socket.io][socket.io].
@@ -395,15 +399,6 @@ 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 bash
-npm t -- -R silent
-npm t -- report text-summary
-```
-
 ## Changelog
 
 The [changelog][changelog] is generated using the useful
@@ -417,12 +412,13 @@ npx auto-changelog -p
 
 See the [LICENSE.txt][license] file for details.
 
-## Roadmap
+## Issues
 
-- [ ] Support for simple lambdas to compose functions more easily.
+See [issues][issues] for roadmap and known bugs.
 
 [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

package/example/typescript/docs/functions/add.md

@@ -8,7 +8,7 @@
 
 > **add**(`a`, `b`): `number`
 
-Defined in: [math.ts:1](https://github.com/bas080/sendscript/blob/45659c51354ac3bbe3bed5ef3826785d8a1a4a32/example/typescript/math.ts#L1)
+Defined in: [math.ts:1](https://github.com/bas080/sendscript/blob/08eb266b06d8998e6849dbc5c9738fbe782ada18/example/typescript/math.ts#L1)
 
 ## Parameters
 

package/example/typescript/docs/functions/square.md

@@ -8,7 +8,7 @@
 
 > **square**(`a`): `number`
 
-Defined in: [math.ts:2](https://github.com/bas080/sendscript/blob/45659c51354ac3bbe3bed5ef3826785d8a1a4a32/example/typescript/math.ts#L2)
+Defined in: [math.ts:2](https://github.com/bas080/sendscript/blob/08eb266b06d8998e6849dbc5c9738fbe782ada18/example/typescript/math.ts#L2)
 
 ## Parameters
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sendscript",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "Blur the line between server and client code.",
   "module": true,
   "main": "index.mjs",

package/parse.mjs

@@ -6,13 +6,14 @@ function flattenSchema (schema) {
 
   for (const item of schema) {
     if (typeof item === 'string') {
-      // leaf function
       obj[item] = true
     } else if (Array.isArray(item)) {
       const [name, children] = item
+
       if (!Array.isArray(children)) {
         throw new Error(`Expected children array for namespace "${name}"`)
       }
+
       obj[name] = flattenSchema(children)
     } else {
       throw new Error('Schema items must be strings or [name, children] arrays')
@@ -38,7 +39,6 @@ const spy = (type, fn) => (...args) => {
   return value
 }
 
-// Recursively resolve awaited values in a parsed tree
 const evaluate = spy('eval', (value, awaits = []) => {
   if (value === undefinedSentinel) return undefined
 
@@ -47,49 +47,41 @@ const evaluate = spy('eval', (value, awaits = []) => {
 
     if (operator === 'await') {
       const [index] = rest
-      // No need to check index. It is closely tied to the program.
-      // if (typeof index !== 'number' || index < 0 || index >= awaitsResolved.length) {
-      //   throw new Error(`Invalid await index: ${index}`);
-      // }
       return awaits[index]
     }
 
     if (operator === 'then') {
       const [v, onResolve, onReject] = rest
-      return evaluate(v, awaits).then(evaluate(onResolve, awaits), evaluate(onReject, awaits))
+      return evaluate(v, awaits).then(
+        evaluate(onResolve, awaits),
+        evaluate(onReject, awaits)
+      )
     }
 
     if (operator === 'call') {
-      // Step 1: evaluate the function itself
       let [fn, args] = rest
       fn = evaluate(fn, awaits)
 
-      // Step 2: evaluate each argument AFTER fn is ready
       for (let i = 0; i < args.length; i++) {
         args[i] = evaluate(args[i], awaits)
       }
 
-      // Step 3: call the function
       return fn(...args)
     }
 
     if (operator === 'quote') {
       const [quoted] = rest
-      return quoted // return as-is without evaluating
+      return quoted
     }
 
-    // fallback: evaluate each element
-    // re-uses the array again.
-
-    for (let index = 0; index < value.length; index++) {
-      const item = value[index]
-      value[index] = evaluate(item, awaits)
+    for (let i = 0; i < value.length; i++) {
+      value[i] = evaluate(value[i], awaits)
     }
+
     return value
   }
 
   if (isPlainObject(value)) {
-    // We muatate the object itself. No need to make a new one.
     for (const key of Object.keys(value)) {
       value[key] = evaluate(value[key], awaits)
     }
@@ -99,23 +91,56 @@ const evaluate = spy('eval', (value, awaits = []) => {
   return value
 })
 
+/**
+ * Default deserializer for leaf nodes.
+ *
+ * @param {string} text
+ * @returns {any}
+ * @public
+ */
 const defaultLeafDeserializer = (text) => JSON.parse(text)
 
-export default (schemaArg, env, deserialize = defaultLeafDeserializer) => {
+/**
+ * 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
+ *
+ * @param {Array<string | [string, Array]>} schemaArg
+ * @param {Object} env - runtime environment for refs
+ * @param {(text: string) => any} [deserialize=defaultLeafDeserializer]
+ * @returns {(program: string) => any|Promise<any>}
+ * @public
+ */
+export default function Parse (schemaArg, env, deserialize = defaultLeafDeserializer) {
   const schema = flattenSchema(schemaArg)
 
+  /**
+   * Parses and executes a serialized program.
+   *
+   * @param {string} program - JSON encoded program
+   * @returns {any|Promise<any>}
+   * @public
+   */
   return function parse (program) {
     debug('program', program)
     const awaits = []
 
-    // Creates the list of awaits that will resolve in order
-    // and also deserializes the leaves.
+    /**
+     * JSON reviver used during parsing.
+     * Converts encoded operators into runtime structures.
+     *
+     * @param {string} key
+     * @param {any} value
+     * @returns {any}
+     */
     const reviver = spy('revive', (key, value) => {
       if (value === null) return value
 
-      if (!Array.isArray(value)) {
-        return value
-      }
+      if (!Array.isArray(value)) return value
 
       const [operator, ...rest] = value
 
@@ -126,7 +151,6 @@ export default (schemaArg, env, deserialize = defaultLeafDeserializer) => {
 
       if (operator === 'await') {
         const [program] = rest
-
         return ['await', awaits.push(program) - 1]
       }
 
@@ -151,19 +175,17 @@ export default (schemaArg, env, deserialize = defaultLeafDeserializer) => {
     })
 
     const parsed = JSON.parse(program, reviver)
-
     debug('parsed', parsed)
 
     if (awaits.length) {
       debug('awaits', awaits)
 
       return (async function () {
-        for (let index = 0; index < awaits.length; index++) {
-          awaits[index] = await evaluate(awaits[index], awaits)
+        for (let i = 0; i < awaits.length; i++) {
+          awaits[i] = await evaluate(awaits[i], awaits)
         }
 
         debug('awaits(awaited)', awaits)
-
         return evaluate(parsed, awaits)
       })()
     }

package/references.mjs

@@ -1,6 +1,19 @@
 import { awaitSymbol, call, ref, then, referenceSymbol } from './symbol.mjs'
 
+/**
+ * Creates a callable reference node bound to a path.
+ * Used to build a lazy/instrumented execution structure.
+ *
+ * @param {Array<string>} path - Path representing the function location in schema.
+ * @returns {Function} Reference function with attached control methods (.then, .catch, toJSON).
+ */
 function instrument (path) {
+  /**
+   * Creates a callable reference invocation.
+   *
+   * @param {...any} args - Arguments passed to the call.
+   * @returns {Function} New instrumented reference node.
+   */
   function reference (...args) {
     const called = instrument(path)
 
@@ -13,6 +26,13 @@ function instrument (path) {
     return called
   }
 
+  /**
+   * Internal helper for building promise-like continuation nodes.
+   *
+   * @param {Function|null} resolve
+   * @param {Function|null} reject
+   * @returns {Function} Instrumented continuation node.
+   */
   function dotThen (resolve, reject) {
     const node = instrument(path)
 
@@ -26,18 +46,32 @@ function instrument (path) {
     return node
   }
 
+  /**
+   * Registers rejection handler (promise-style).
+   *
+   * @param {Function} reject
+   * @returns {Function}
+   */
   reference.catch = (reject) => {
     return dotThen(null, reject)
   }
 
+  /**
+   * Handles async chaining or awaiting logic.
+   *
+   * If resolve/reject contain a reference marker, it behaves like a .then chain.
+   * Otherwise it behaves like an await wrapper.
+   *
+   * @param {Function} resolve
+   * @param {Function} reject
+   * @returns {Function|any}
+   */
   reference.then = (resolve, reject) => {
-    // That is how we know if it is an await or a .then call.
     if (resolve?.[referenceSymbol] || reject?.[referenceSymbol]) {
       return dotThen(resolve, reject)
     }
 
     const awaited = instrument(path)
-    // Prevent infinite recur
     delete awaited.then
 
     awaited.toJSON = () => ({
@@ -48,6 +82,11 @@ function instrument (path) {
     return resolve(awaited)
   }
 
+  /**
+   * JSON representation of the reference path node.
+   *
+   * @returns {{ref: symbol, path: Array<string>}}
+   */
   reference.toJSON = () => ({
     [ref]: ref,
     path
@@ -58,17 +97,29 @@ function instrument (path) {
   return reference
 }
 
-export default function module (schema, parentPath = []) {
+/**
+ * Builds a nested API structure from a schema definition.
+ *
+ * Schema supports:
+ * - string => leaf function node
+ * - [name, children] => namespace with nested schema
+ *
+ * @param {Array<string | [string, Array]>} schema
+ * @param {Array<string>} [parentPath=[]]
+ * @returns {Object} Nested instrumented API object
+ *
+ * @throws {Error} If schema format is invalid
+ * @public
+ */
+export default function References (schema, parentPath = []) {
   return schema.reduce((acc, item) => {
     if (typeof item === 'string') {
-      // leaf function
       acc[item] = instrument([...parentPath, item])
     } else if (Array.isArray(item)) {
       const [name, children] = item
 
       if (Array.isArray(children)) {
-        // recurse: children can be strings or [name, children] arrays
-        acc[name] = module(children, [...parentPath, name])
+        acc[name] = References(children, [...parentPath, name])
       } else {
         throw new Error(`Expected children array for namespace "${name}"`)
       }

package/stringify.mjs

@@ -10,6 +10,7 @@ import {
 const debug = Debug.extend('stringify')
 
 const keywords = ['ref', 'call', 'quote', 'await', 'leaf']
+
 const isKeyword = (v) => keywords.includes(v)
 
 const isPlainObject = (value) => {
@@ -18,26 +19,26 @@ const isPlainObject = (value) => {
   return proto === Object.prototype || proto === null
 }
 
-// Recursively transform a program tree, encoding SendScript operators and leaf values
 function transformValue (value, leafSerializer) {
   debug(value)
 
-  if (value === null) {
-    return null
-  }
+  if (value === null) return null
 
-  // Normalize SendScript wrapper functions (ref, call, await)
+  // unwrap function wrappers (instrumented nodes)
   if (typeof value === 'function' && typeof value.toJSON === 'function') {
     return transformValue(value.toJSON(), leafSerializer)
   }
 
-  // Encode SendScript operators
   if (value && value[ref]) {
     return ['ref', ...value.path]
   }
 
   if (value && value[call]) {
-    return ['call', transformValue(value.ref, leafSerializer), transformValue(value.args, leafSerializer)]
+    return [
+      'call',
+      transformValue(value.ref, leafSerializer),
+      transformValue(value.args, leafSerializer)
+    ]
   }
 
   if (value && value[awaitSymbol]) {
@@ -45,22 +46,27 @@ function transformValue (value, leafSerializer) {
   }
 
   if (value && value[then]) {
-    return ['then', transformValue(value.ref, leafSerializer), transformValue(value.resolve || null, leafSerializer), transformValue(value.reject || null, leafSerializer)]
+    return [
+      'then',
+      transformValue(value.ref, leafSerializer),
+      transformValue(value.resolve || null, leafSerializer),
+      transformValue(value.reject || null, leafSerializer)
+    ]
   }
 
-  // Handle arrays: quote keyword operators, transform other arrays recursively
   if (Array.isArray(value)) {
     const [operator, ...rest] = value
 
     if (isKeyword(operator)) {
-      // Quote reserved keyword strings to preserve them as data
-      return [['quote', operator], ...rest.map((item) => transformValue(item, leafSerializer))]
+      return [
+        ['quote', operator],
+        ...rest.map((item) => transformValue(item, leafSerializer))
+      ]
     }
 
     return value.map((item) => transformValue(item, leafSerializer))
   }
 
-  // Recurse into plain objects
   if (isPlainObject(value)) {
     const result = {}
 
@@ -71,21 +77,45 @@ function transformValue (value, leafSerializer) {
     return result
   }
 
-  // Encode non-JSON leaf values (Date, RegExp, BigInt, etc.)
   return ['leaf', leafSerializer(value)]
 }
 
+/**
+ * Default strict serializer for leaf values.
+ *
+ * Rejects non-JSON-safe values.
+ *
+ * @param {any} x
+ * @returns {string}
+ * @public
+ */
 function strictStringify (x) {
   const typeOf = typeof x
 
   if (typeOf === 'object' || typeOf === 'function' || x === undefined) {
-    throw new SendScriptSerializationError(`Cannot and should not attempt to serialize ${x}`)
+    throw new SendScriptSerializationError(
+      `Cannot and should not attempt to serialize ${x}`
+    )
   }
 
   return JSON.stringify(x)
 }
 
-export default function stringify (leafSerializer = strictStringify) {
+/**
+ * Creates a stringify function for SendScript AST structures.
+ *
+ * @param {(value: any) => string} [leafSerializer=strictStringify]
+ * @returns {(program: any) => string}
+ * @public
+ */
+export default function Stringify (leafSerializer = strictStringify) {
+  /**
+   * Serializes a program into a JSON string representation.
+   *
+   * @param {any} program
+   * @returns {string}
+   * @public
+   */
   function stringify (program) {
     return JSON.stringify(transformValue(program, leafSerializer))
   }