sendscript 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -4,8 +4,23 @@ 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).
 
+#### [v1.1.0](https://github.com/bas080/sendscript/compare/v1.0.6...v1.1.0)
+
+- Support custom serialization of leaf nodes [`d56f1b7`](https://github.com/bas080/sendscript/commit/d56f1b750e2d7faf72d69f9ba8e9bb62ef5ebce7)
+- Support nested modules [`88e69e5`](https://github.com/bas080/sendscript/commit/88e69e5c05ddb85aac1797a020e92519c986e89f)
+- Document new nesting and leaf serialization feature [`b3ee9f6`](https://github.com/bas080/sendscript/commit/b3ee9f693dc6137b01c9f0072aa2dd1e940f07c9)
+
+#### [v1.0.6](https://github.com/bas080/sendscript/compare/v1.0.5...v1.0.6)
+
+> 6 April 2026
+
+- Update tap to 21.6.3 [`c1769d9`](https://github.com/bas080/sendscript/commit/c1769d9a24148e63d27b0e5a7456213bec64763e)
+- Add introduction to readme [`a21a494`](https://github.com/bas080/sendscript/commit/a21a494616d5ad8c99f9a2904ef529ea85104a99)
+
 #### [v1.0.5](https://github.com/bas080/sendscript/compare/v1.0.4...v1.0.5)
 
+> 5 April 2026
+
 - Add publish to npm workflow [`aaaa97d`](https://github.com/bas080/sendscript/commit/aaaa97d1024d6b5ed574a2cd103035949ec8280d)
 
 #### [v1.0.4](https://github.com/bas080/sendscript/compare/v1.0.3...v1.0.4)

package/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+
+For the README.mz examples to work we need sendscript to be linked.
+
+```bash bash > /dev/null
+set -e
+
+npm link
+npm link sendscript
+cd ./example
+npm ci
+npm link sendscript
+```
+
+Generate the README from the mz file.
+
+```bash bash
+markatzea ./README.mz | tee ./README.md
+
+npx markdown-toc -i README.md
+
+git add *.md ./example
+```

package/README.md

@@ -9,6 +9,7 @@ Write JS code that you can run on servers, browsers or other clients.
 
 <!-- toc -->
 
+- [Introduction](#introduction)
 - [Socket example](#socket-example)
   * [Module](#module)
   * [Server](#server)
@@ -16,6 +17,12 @@ Write JS code that you can run on servers, browsers or other clients.
 - [Repl](#repl)
 - [Async/Await](#asyncawait)
 - [TypeScript](#typescript)
+- [Schema and Nested Modules](#schema-and-nested-modules)
+  * [Defining a Nested Module](#defining-a-nested-module)
+- [Validation (using Zod)](#validation-using-zod)
+  * [Validating structured input](#validating-structured-input)
+- [Leaf Serializer](#leaf-serializer)
+  * [Example with superjson](#example-with-superjson)
 - [Tests](#tests)
 - [Formatting](#formatting)
 - [Changelog](#changelog)
@@ -25,6 +32,75 @@ Write JS code that you can run on servers, browsers or other clients.
 
 <!-- tocstop -->
 
+## Introduction
+
+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.
+
+- [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.
+
+SendScript produces an intermediate JSON representation of the program. Let's see what that looks like.
+
+```js
+import stringify from 'sendscript/stringify.mjs'
+import module from 'sendscript/module.mjs'
+
+const { add } = module(['add'])
+
+console.log(stringify(add(1,2)))
+```
+```json
+["call",["ref","add"],[["leaf","1"],["leaf","2"]]]
+```
+
+We can then parse that JSON and it will evaluate down to a value.
+
+```js
+import Parse from 'sendscript/parse.mjs'
+
+const module = {
+  add(a, b) {
+    return a + b
+  }
+}
+
+const parse = Parse(module)
+
+const program = '["call",["ref","add"],[1,2]]'
+
+console.log(parse(program))
+```
+```json
+3
+```
+
+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:
+
+- The `module` 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.
@@ -33,17 +109,6 @@ needs.
 
 For this example we'll use [socket.io][socket.io].
 
-```bash
-set -e
-
-npm link
-cd ./example
-npm ci
-npm link sendscript
-```
-
-> We use the `--no-save` option because it's only for demonstration purposes.
-
 ### Module
 
 We write a simple module.
@@ -234,7 +299,7 @@ npm install --no-save \
   typedoc \
   typedoc-plugin-markdown
 
-typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
+npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
 ```
 
 You can see the docs [here](./example/typescript/docs/globals.md)
@@ -244,6 +309,128 @@ You can see the docs [here](./example/typescript/docs/globals.md)
 > 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.
+
+### Defining a Nested Module
+
+You can define a schema as either:
+
+1. **An object with nested objects** – submodules.
+2. **An array of function names** – automatically instrumented.
+
+```js
+import module from 'sendscript/module.mjs'
+
+const myModule = module({
+  math: ['add', 'sub'],
+
+  // Use an object with keys and true value
+  vector: {
+    add: true,
+    multiply: true
+  },
+
+  // or use an array.
+  utils: ['identity', 'always'],
+})
+```
+
+Functions are referenced via their **path in the module tree**:
+
+```js
+const { math, vector } = myModule
+
+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).
+
+### Validating structured input
+
+```js
+const userSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  roles: z.array(z.string())
+})
+
+export function createUser(user) {
+  userSchema.parse(user)
+
+  return { success: true }
+}
+```
+
+**Benefits**:
+
+- 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.
+
+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:
+
+```js
+import SuperJSON from 'superjson'
+import stringify from 'sendscript/stringify.mjs'
+import Parse from 'sendscript/parse.mjs'
+import module from 'sendscript/module.mjs'
+
+const leafSerializer = (value) => {
+  if (value === undefined) return JSON.stringify({ __undefined__: true })
+  return JSON.stringify(SuperJSON.serialize(value))
+}
+
+const leafDeserializer = (text) => {
+  const parsed = JSON.parse(text)
+  if (parsed && parsed.__undefined__ === true) return undefined
+  return SuperJSON.deserialize(parsed)
+}
+
+const { processData } = module(['processData'])
+
+// Program with Date, RegExp, and other types
+const program = {
+  createdAt: new Date('2020-01-01T00:00:00.000Z'),
+  pattern: /foo/gi,
+  count: BigInt('9007199254740992'),
+  items: new Set([1, 2, 3]),
+  mapping: new Map([['a', 1], ['b', 2]])
+}
+
+// Serialize with custom leaf serializer
+const json = stringify(processData(program), leafSerializer)
+
+// Parse with custom leaf deserializer
+const parse = Parse({
+  processData: (data) => ({
+    success: true,
+    received: data
+  })
+})
+
+const result = parse(json, leafDeserializer)
+```
+
+The leaf wrapper format is `['leaf', serializedPayload]`, making it unambiguous and safe from colliding with SendScript operators.
+
 ## Tests
 
 Tests with 100% code coverage.
@@ -254,19 +441,19 @@ npm t -- report text-summary
 ```
 ```
 
-> sendscript@1.0.5 test
+> sendscript@1.1.0 test
 > tap -R silent
 
 
-> sendscript@1.0.5 test
+> sendscript@1.1.0 test
 > tap report text-summary
 
 
 =============================== Coverage summary ===============================
-Statements   : 100% ( 245/245 )
-Branches     : 100% ( 74/74 )
-Functions    : 100% ( 18/18 )
-Lines        : 100% ( 245/245 )
+Statements   : 100% ( 328/328 )
+Branches     : 100% ( 138/138 )
+Functions    : 100% ( 23/23 )
+Lines        : 100% ( 328/328 )
 ================================================================================
 ```
 

package/README.mz

@@ -9,6 +9,69 @@ Write JS code that you can run on servers, browsers or other clients.
 
 <!-- toc -->
 
+## Introduction
+
+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.
+
+- [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.
+
+SendScript produces an intermediate JSON representation of the program. Let's see what that looks like.
+
+```js|json node --input-type=module | tee /tmp/sendscript.json
+import stringify from 'sendscript/stringify.mjs'
+import module from 'sendscript/module.mjs'
+
+const { add } = module(['add'])
+
+console.log(stringify(add(1,2)))
+```
+
+We can then parse that JSON and it will evaluate down to a value.
+
+```js|json node --input-type=module
+import Parse from 'sendscript/parse.mjs'
+
+const module = {
+  add(a, b) {
+    return a + b
+  }
+}
+
+const parse = Parse(module)
+
+const program = '["call",["ref","add"],[1,2]]'
+
+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:
+
+- The `module` 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.
@@ -17,17 +80,6 @@ needs.
 
 For this example we'll use [socket.io][socket.io].
 
-```bash bash > /dev/null
-set -e
-
-npm link
-cd ./example
-npm ci
-npm link sendscript
-```
-
-> We use the `--no-save` option because it's only for demonstration purposes.
-
 ### Module
 
 We write a simple module.
@@ -184,7 +236,7 @@ npm install --no-save \
   typedoc \
   typedoc-plugin-markdown
 
-typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
+npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
 ```
 
 You can see the docs [here](./example/typescript/docs/globals.md)
@@ -194,6 +246,128 @@ You can see the docs [here](./example/typescript/docs/globals.md)
 > 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.
+
+### Defining a Nested Module
+
+You can define a schema as either:
+
+1. **An object with nested objects** – submodules.
+2. **An array of function names** – automatically instrumented.
+
+```js
+import module from 'sendscript/module.mjs'
+
+const myModule = module({
+  math: ['add', 'sub'],
+
+  // Use an object with keys and true value
+  vector: {
+    add: true,
+    multiply: true
+  },
+
+  // or use an array.
+  utils: ['identity', 'always'],
+})
+```
+
+Functions are referenced via their **path in the module tree**:
+
+```js
+const { math, vector } = myModule
+
+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).
+
+### Validating structured input
+
+```js
+const userSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  roles: z.array(z.string())
+})
+
+export function createUser(user) {
+  userSchema.parse(user)
+
+  return { success: true }
+}
+```
+
+**Benefits**:
+
+- 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.
+
+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:
+
+```js
+import SuperJSON from 'superjson'
+import stringify from 'sendscript/stringify.mjs'
+import Parse from 'sendscript/parse.mjs'
+import module from 'sendscript/module.mjs'
+
+const leafSerializer = (value) => {
+  if (value === undefined) return JSON.stringify({ __undefined__: true })
+  return JSON.stringify(SuperJSON.serialize(value))
+}
+
+const leafDeserializer = (text) => {
+  const parsed = JSON.parse(text)
+  if (parsed && parsed.__undefined__ === true) return undefined
+  return SuperJSON.deserialize(parsed)
+}
+
+const { processData } = module(['processData'])
+
+// Program with Date, RegExp, and other types
+const program = {
+  createdAt: new Date('2020-01-01T00:00:00.000Z'),
+  pattern: /foo/gi,
+  count: BigInt('9007199254740992'),
+  items: new Set([1, 2, 3]),
+  mapping: new Map([['a', 1], ['b', 2]])
+}
+
+// Serialize with custom leaf serializer
+const json = stringify(processData(program), leafSerializer)
+
+// Parse with custom leaf deserializer
+const parse = Parse({
+  processData: (data) => ({
+    success: true,
+    received: data
+  })
+})
+
+const result = parse(json, leafDeserializer)
+```
+
+The leaf wrapper format is `['leaf', serializedPayload]`, making it unambiguous and safe from colliding with SendScript operators.
+
 ## Tests
 
 Tests with 100% code coverage.

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/aaaa97d1024d6b5ed574a2cd103035949ec8280d/example/typescript/math.ts#L1)
+Defined in: [math.ts:1](https://github.com/bas080/sendscript/blob/68bfab27a561a994381cdcf5a7cf367e29a2d07d/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/aaaa97d1024d6b5ed574a2cd103035949ec8280d/example/typescript/math.ts#L2)
+Defined in: [math.ts:2](https://github.com/bas080/sendscript/blob/68bfab27a561a994381cdcf5a7cf367e29a2d07d/example/typescript/math.ts#L2)
 
 ## Parameters
 

package/index.test.mjs

@@ -1,7 +1,14 @@
 import { test } from 'tap'
-import Sendscript from './index.mjs'
-
-const module = {
+import stringify from './stringify.mjs'
+import ssparse from './parse.mjs'
+import module from './module.mjs'
+
+const myModule = {
+  nested: {
+    again: {
+      T: () => true
+    }
+  },
   add: (a, b) => a + b,
   identity: (x) => x,
   concat: (a, b) => a.concat(b),
@@ -18,13 +25,32 @@ const module = {
   asyncAdd: async (a, b) => a + b,
   aPromise: Promise.resolve(42),
   delayedIdentity: async (x) => x,
+  nullProto: () => {
+    const obj = Object.create(null)
+    obj.b = 'c'
+    return obj
+  },
   Function,
   Promise
 }
 
-const sendscript = Sendscript(module)
-const { parse, stringify } = sendscript
-const run = (program) => parse(stringify(program))
+const schema = Object.keys(myModule).reduce((acc, key) => {
+  acc[key] = true
+
+  return acc
+}, {})
+
+schema.nested = { again: ['T'] }
+
+const sendscript = {
+  stringify,
+  parse: ssparse(myModule),
+  module: module(schema)
+}
+
+const { parse } = sendscript
+
+const run = (program) => sendscript.parse(sendscript.stringify(program))
 
 const RealPromise = Promise
 
@@ -46,9 +72,16 @@ test('should evaluate basic expressions correctly', async (t) => {
     concat,
     identity,
     always,
-    multiply3
+    multiply3,
+    nested
   } = sendscript.module
 
+  t.test('calling nested function works', t => {
+    t.equal(run(nested.again.T()), true)
+
+    t.end()
+  })
+
   t.test('nested await works', async (t) => {
     // Async identity passthrough
     const resolvedId = await delayedIdentity
@@ -177,6 +210,16 @@ test('should evaluate basic expressions correctly', async (t) => {
       run(identity(['ref', 'hello'])),
       run(identity(toArray('ref', 'hello')))
     )
+    t.strictSame(
+      run(identity(['leaf', 1, 2, 3])),
+      ['leaf', 1, 2, 3]
+    )
+    t.end()
+  })
+
+  t.test('null-prototype object traversal', (t) => {
+    const { nullProto } = sendscript.module
+    t.strictSame(run({ a: nullProto() }), { a: { b: 'c' } })
     t.end()
   })
 

package/leaf-serializer-property.test.mjs

@@ -0,0 +1,149 @@
+import { test } from 'tap'
+import { createRequire } from 'module'
+import SuperJSON from 'superjson'
+
+const require = createRequire(import.meta.url)
+const { check, gen } = require('tape-check')
+
+const leafSerializer = (value) => {
+  if (value === undefined) return JSON.stringify({ __sendscript_undefined__: true })
+  return JSON.stringify(SuperJSON.serialize(value))
+}
+
+const leafDeserializer = (text) => {
+  const parsed = JSON.parse(text)
+  if (parsed && parsed.__sendscript_undefined__ === true) return undefined
+  return SuperJSON.deserialize(parsed)
+}
+
+// Helper to compare values accounting for types that can't use ===
+const valueEquals = (a, b) => {
+  if (a === b) return true
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+  if (a instanceof RegExp && b instanceof RegExp) return a.source === b.source && a.flags === b.flags
+  if (a instanceof Set && b instanceof Set) {
+    if (a.size !== b.size) return false
+    for (const item of a) {
+      if (!b.has(item)) return false
+    }
+    return true
+  }
+  if (a instanceof Map && b instanceof Map) {
+    if (a.size !== b.size) return false
+    for (const [key, val] of a) {
+      if (!b.has(key) || !valueEquals(val, b.get(key))) return false
+    }
+    return true
+  }
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+// Helper to get a human-readable type name
+const getTypeInfo = (value) => {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (value instanceof Date) return 'Date'
+  if (value instanceof RegExp) return 'RegExp'
+  if (value instanceof Set) return 'Set'
+  if (value instanceof Map) return 'Map'
+  if (typeof value === 'bigint') return 'BigInt'
+  return typeof value
+}
+
+// Property 1: Round-trip - any value that can be serialized should deserialize to an equal value
+test('property: round-trip serialization preserves value', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    try {
+      const serialized = leafSerializer(value)
+      const deserialized = leafDeserializer(serialized)
+      const typeInfo = getTypeInfo(value)
+      t.ok(valueEquals(deserialized, value), `Round-trip preserved ${typeInfo}`)
+    } catch (e) {
+      // If serialization fails on a particular value, that's acceptable
+      // (not all values may be serializable)
+      const typeInfo = getTypeInfo(value)
+      t.pass(`Serialization of ${typeInfo} threw: ${e.message}`)
+    }
+  }
+))
+
+// Property 2: Determinism - serializing the same value repeatedly produces identical results
+test('property: serialization is deterministic', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    try {
+      const serialized1 = leafSerializer(value)
+      const serialized2 = leafSerializer(value)
+      const typeInfo = getTypeInfo(value)
+      t.equal(serialized1, serialized2, `Serialization of ${typeInfo} is deterministic`)
+    } catch (e) {
+      const typeInfo = getTypeInfo(value)
+      t.pass(`Serialization threw for ${typeInfo}: ${e.message}`)
+    }
+  }
+))
+
+// Property 3: Valid JSON - serialized output is always valid JSON
+test('property: serialized output is valid JSON', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    try {
+      const serialized = leafSerializer(value)
+      const parsed = JSON.parse(serialized)
+      t.ok(typeof parsed === 'object' || typeof parsed === 'string', 'Parsed JSON is an object or string')
+    } catch (e) {
+      t.fail(`Invalid JSON output for ${getTypeInfo(value)}: ${e.message}`)
+    }
+  }
+))
+
+// Property 4: Undefined handling - undefined values are preserved through round-trip
+test('property: undefined values are preserved through serialization', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    if (value === undefined) {
+      const serialized = leafSerializer(value)
+      const deserialized = leafDeserializer(serialized)
+      t.equal(deserialized, undefined, 'Undefined preserved through serialization')
+    } else {
+      t.pass('Value was not undefined')
+    }
+  }
+))
+
+// Property 5: Type distinctness - Different values should have different serializations (when possible)
+test('property: different primitives have different serializations', check(
+  gen.primitive,
+  gen.primitive,
+  (t, val1, val2) => {
+    t.plan(1)
+    if (val1 !== val2 && !(Number.isNaN(val1) && Number.isNaN(val2))) {
+      const ser1 = leafSerializer(val1)
+      const ser2 = leafSerializer(val2)
+      t.not(ser1, ser2, `Different primitives ${getTypeInfo(val1)} and ${getTypeInfo(val2)} have different serializations`)
+    } else {
+      t.pass('Primitives are equal or both NaN')
+    }
+  }
+))
+
+// Property 6: Idempotence of serialization - Re-parsing serialized value produces same serialization
+test('property: serialization round-trip is stable', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    try {
+      const ser1 = leafSerializer(value)
+      const deser1 = leafDeserializer(ser1)
+      const ser2 = leafSerializer(deser1)
+      t.equal(ser1, ser2, `Serialization is stable for ${getTypeInfo(value)}`)
+    } catch (e) {
+      t.pass(`Serialization error for ${getTypeInfo(value)}: ${e.message}`)
+    }
+  }
+))

package/leaf-serializer.test.mjs

@@ -0,0 +1,76 @@
+import { test } from 'tap'
+import SuperJSON from 'superjson'
+import Sendscript from './index.mjs'
+
+const leafSerializer = (value) => {
+  if (value === undefined) return JSON.stringify({ __sendscript_undefined__: true })
+  return JSON.stringify(SuperJSON.serialize(value))
+}
+
+const leafDeserializer = (text) => {
+  const parsed = JSON.parse(text)
+  if (parsed && parsed.__sendscript_undefined__ === true) return undefined
+  return SuperJSON.deserialize(parsed)
+}
+
+const module = {
+  identity: (x) => x
+}
+
+const sendscript = Sendscript(Object.keys(module))
+const { parse, stringify } = sendscript
+const run = (program, serializer, deserializer) =>
+  parse(stringify(program, serializer), deserializer)
+
+test('custom leaf serializer/deserializer using superjson', async (t) => {
+  const value = {
+    date: new Date('2020-01-01T00:00:00.000Z'),
+    regex: /abc/gi,
+    big: BigInt('123456789012345678901234567890'),
+    undef: undefined,
+    nested: {
+      set: new Set([1, 2, 3]),
+      map: new Map([['a', 1], ['b', 2]])
+    }
+  }
+
+  const result = await run(value, leafSerializer, leafDeserializer)
+
+  t.ok(result.date instanceof Date)
+  t.equal(result.date.toISOString(), value.date.toISOString())
+
+  t.ok(result.regex instanceof RegExp)
+  t.equal(result.regex.source, 'abc')
+  t.equal(result.regex.flags, 'gi')
+
+  t.equal(result.big, value.big)
+
+  t.ok(Object.prototype.hasOwnProperty.call(result, 'undef'))
+  t.equal(result.undef, undefined)
+
+  t.ok(result.nested.set instanceof Set)
+  t.strictSame(Array.from(result.nested.set), [1, 2, 3])
+
+  t.ok(result.nested.map instanceof Map)
+  t.strictSame(Array.from(result.nested.map.entries()), [['a', 1], ['b', 2]])
+
+  t.end()
+})
+
+test('default leaf deserializer when not provided', async (t) => {
+  const value = { a: 1, b: 'hello' }
+  const result = await run(value)
+
+  t.strictSame(result, value)
+  t.end()
+})
+
+test('default leaf deserializer handles undefined parameter', (t) => {
+  const parse = Sendscript({}).parse
+  // Create a simple JSON with a leaf then parse using default deserializer
+  // The reviver will never pass undefined to deserializer, but we test it defensively
+  const json = '["leaf","{\\"test\\":1}"]'
+  const result = parse(json)
+  t.strictSame(result, { test: 1 })
+  t.end()
+})

package/module.mjs

@@ -1,12 +1,8 @@
-import {
-  awaitSymbol,
-  call,
-  ref
-} from './symbol.mjs'
+import { awaitSymbol, call, ref } from './symbol.mjs'
 
-function instrument (name) {
+function instrument (path) {
   function reference (...args) {
-    const called = instrument(name)
+    const called = instrument(path)
 
     called.toJSON = () => ({
       [call]: call,
@@ -19,8 +15,7 @@ function instrument (name) {
   }
 
   reference.then = (resolve) => {
-    const awaited = instrument(name)
-
+    const awaited = instrument(path)
     delete awaited.then
 
     awaited.toJSON = () => ({
@@ -35,18 +30,31 @@ function instrument (name) {
   reference.toJSON = () => ({
     [ref]: ref,
     reference: true,
-    name
+    path
   })
 
   return reference
 }
 
-export default function module (schema) {
-  if (!Array.isArray(schema)) return module(Object.keys(schema))
+export default function module (schema, parentPath = []) {
+  if (Array.isArray(schema)) {
+    return schema.reduce((acc, name) => {
+      acc[name] = instrument([...parentPath, name])
+      return acc
+    }, {})
+  }
+
+  return Object.keys(schema).reduce((acc, key) => {
+    const value = schema[key]
 
-  return schema.reduce((api, name) => {
-    api[name] = instrument(name)
+    if (Array.isArray(value)) {
+      acc[key] = module(value, [...parentPath, key])
+    } else if (typeof value === 'object' && value !== null) {
+      acc[key] = module(value, [...parentPath, key])
+    } else {
+      acc[key] = instrument([...parentPath, key])
+    }
 
-    return api
+    return acc
   }, {})
 }

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "sendscript",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Blur the line between server and client code.",
   "module": true,
   "main": "index.mjs",
+  "bin": "./cli.mjs",
   "keywords": [
     "rpc",
     "json",
@@ -17,13 +18,15 @@
   },
   "scripts": {
     "test": "tap",
-    "version": "npm run docs && git add *.md example",
-    "docs": "markatzea README.mz | tee README.md && npx markdown-toc -i README.md"
+    "version": "npm run docs",
+    "docs": "markatzea CONTRIBUTING.md"
   },
   "author": "Bas Huis",
   "license": "MIT",
   "devDependencies": {
-    "tap": "^21.6.2"
+    "superjson": "^2.2.6",
+    "tap": "^21.6.3",
+    "tape-check": "^1.0.0-rc.0"
   },
   "dependencies": {
     "debug": "^4.4.3"

package/parse.mjs

@@ -1,43 +1,100 @@
 import Debug from './debug.mjs'
-import isNil from './is-nil.mjs'
 import { SendScriptReferenceError } from './error.mjs'
 
 const debug = Debug.extend('parse')
 
-export default (env) =>
-  function parse (program) {
-    debug('program', program)
+const isThenable = (value) => (
+  value != null && typeof value.then === 'function'
+)
 
-    const awaits = []
-    const resolved = {}
+const isAwaitPromise = Symbol('sendscript-await')
+const undefinedSentinel = Symbol('sendscript-undefined')
 
-    JSON.parse(program, (key, value) => {
-      if (!Array.isArray(value)) return value
+const isPlainObject = (value) => {
+  if (!value || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
 
-      const [operator, ...rest] = value
+const markAwait = (promise) => {
+  promise[isAwaitPromise] = true
+  return promise
+}
 
-      if (operator === 'await') {
-        const [program, awaitId] = rest
-
-        awaits.push(((program, awaitId) => async () => {
-          resolved[awaitId] = await JSON.parse(
-            JSON.stringify(program),
-            reviver
-          )
-        })(program, awaitId))
-      }
+const isExplicitAwait = (value) => (
+  isThenable(value) && value[isAwaitPromise] === true
+)
 
-      return value
+// Recursively resolve awaited values in a parsed tree
+const resolveAwaitedValues = (value) => {
+  if (value === undefinedSentinel) return undefined
+
+  if (isThenable(value)) {
+    return isExplicitAwait(value)
+      ? markAwait(value.then(resolveAwaitedValues))
+      : value
+  }
+
+  if (Array.isArray(value)) {
+    let hasAwait = false
+    const result = value.map((item) => {
+      const resolved = resolveAwaitedValues(item)
+      if (isExplicitAwait(resolved)) hasAwait = true
+      return resolved
     })
 
-    const spy = fn => (...args) => {
-      const value = fn(...args)
-      debug(args, ' => ', value)
-      return value
+    if (!hasAwait) return result
+
+    const awaited = result.map((item, index) =>
+      isExplicitAwait(item)
+        ? Promise.resolve(item).then((resolved) => {
+          result[index] = resolved
+          return resolved
+        })
+        : item
+    )
+
+    return markAwait(Promise.all(awaited).then(() => result))
+  }
+
+  if (isPlainObject(value)) {
+    const result = {}
+    const promises = []
+
+    for (const key of Object.keys(value)) {
+      const resolved = resolveAwaitedValues(value[key])
+      if (isExplicitAwait(resolved)) {
+        promises.push(
+          Promise.resolve(resolved).then((resolvedValue) => {
+            result[key] = resolvedValue
+          })
+        )
+      } else {
+        result[key] = resolved
+      }
     }
 
+    if (!promises.length) return result
+    return markAwait(Promise.all(promises).then(() => result))
+  }
+
+  return value
+}
+
+const spy = (fn) => (...args) => {
+  const value = fn(...args)
+  debug(args, ' => ', value)
+  return value
+}
+
+const defaultLeafDeserializer = (text) => JSON.parse(text)
+
+export default (env) =>
+  function parse (program, deserialize = defaultLeafDeserializer) {
+    debug('program', program)
+
     const reviver = spy((key, value) => {
-      if (isNil(value)) return value
+      if (value === null) return value
 
       if (!Array.isArray(value)) {
         return value
@@ -45,48 +102,61 @@ export default (env) =>
 
       const [operator, ...rest] = value
 
-      if (operator === 'await') {
-        const [, awaitId] = rest
-        debug('read awaits', resolved[awaitId], awaitId)
+      if (operator === 'leaf') {
+        const leafValue = deserialize(rest[0])
+        return leafValue === undefined ? undefinedSentinel : leafValue
+      }
 
-        return resolved[awaitId]
+      if (operator === 'await') {
+        const [program] = rest
+        return markAwait(Promise.resolve(program))
       }
 
       if (Array.isArray(operator) && operator[0] === 'quote') {
         const [, quoted] = operator
-
         return [quoted, ...rest]
       }
 
       if (operator === 'call') {
         const [fn, args] = rest
-
-        return fn(...args)
+        const resolvedFn = isExplicitAwait(fn) ? Promise.resolve(fn) : fn
+        const resolvedArgs = resolveAwaitedValues(args)
+
+        if (isExplicitAwait(resolvedFn) || isExplicitAwait(resolvedArgs)) {
+          const promiseFn = isExplicitAwait(resolvedFn)
+            ? Promise.resolve(resolvedFn)
+            : resolvedFn
+          const promiseArgs = isExplicitAwait(resolvedArgs)
+            ? Promise.resolve(resolvedArgs)
+            : resolvedArgs
+
+          return Promise.all([promiseFn, promiseArgs])
+            .then(([resolvedFnValue, resolvedArgsValue]) => resolvedFnValue(...resolvedArgsValue))
+        }
+
+        return fn(...resolvedArgs)
       }
 
       if (operator === 'ref') {
-        const [name] = rest
-
-        if (Object.hasOwn(env, name)) return env[name]
-
-        throw new SendScriptReferenceError({ key, value })
+        const path = rest // e.g., ["math","add"]
+        let current = env
+
+        for (const segment of path) {
+          if (current && Object.hasOwn(current, segment)) {
+            current = current[segment]
+          } else {
+            throw new SendScriptReferenceError({ key, value })
+          }
+        }
+
+        return current
       }
 
       return value
     })
 
-    if (awaits.length) {
-      return sequential(awaits).then(() => {
-        return JSON.parse(program, reviver)
-      })
-    }
+    const parsed = JSON.parse(program, reviver)
+    const result = resolveAwaitedValues(parsed)
 
-    return JSON.parse(program, reviver)
+    return result
   }
-
-function sequential (promises) {
-  return promises.reduce(
-    (acc, curr) => acc.then(results => curr().then(res => [...results, res])),
-    Promise.resolve([])
-  )
-}

package/stringify.mjs

@@ -1,5 +1,4 @@
 import Debug from './debug.mjs'
-import isNil from './is-nil.mjs'
 import {
   awaitSymbol,
   call,
@@ -8,59 +7,68 @@ import {
 
 const debug = Debug.extend('stringify')
 
-const replaced = Symbol('replaced')
-const keywords = ['ref', 'call', 'quote', 'await']
+const keywords = ['ref', 'call', 'quote', 'await', 'leaf']
 const isKeyword = (v) => keywords.includes(v)
-let awaitId = -1
 
-function replacer (key, value) {
-  debug(this, key, value)
-
-  if (isNil(value)) {
-    return value
-  }
-
-  if (value[ref]) {
-    const result = ['ref', value.name]
+const isPlainObject = (value) => {
+  if (!value || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
 
-    result[replaced] = replaced
+// Recursively transform a program tree, encoding SendScript operators and leaf values
+function transformValue (value, leafSerializer) {
+  debug(value)
 
-    return result
+  if (value === null) {
+    return null
   }
 
-  if (value[call]) {
-    const result = ['call', value.ref, value.args]
-
-    result[replaced] = replaced
-
-    return result
+  // Normalize SendScript wrapper functions (ref, call, await)
+  if (typeof value === 'function' && typeof value.toJSON === 'function') {
+    return transformValue(value.toJSON(), leafSerializer)
   }
 
-  if (value[awaitSymbol]) {
-    awaitId += 1
-    const result = ['await', value.ref, awaitId]
+  // Encode SendScript operators
+  if (value && value[ref]) {
+    return ['ref', ...value.path]
+  }
 
-    result[replaced] = replaced
+  if (value && value[call]) {
+    return ['call', transformValue(value.ref, leafSerializer), transformValue(value.args, leafSerializer)]
+  }
 
-    return result
+  if (value && value[awaitSymbol]) {
+    return ['await', transformValue(value.ref, leafSerializer)]
   }
 
-  // Quote only the reserved string and not the complete array. Quoted values
-  // will be unquoted on parse. A quoted quote also.
-  if (!value[replaced] && Array.isArray(value)) {
+  // Handle arrays: quote keyword operators, transform other arrays recursively
+  if (Array.isArray(value)) {
     const [operator, ...rest] = value
 
     if (isKeyword(operator)) {
-      const quoted = ['quote', operator]
-      quoted[replaced] = replaced
+      // Quote reserved keyword strings to preserve them as data
+      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 = {}
 
-      return [quoted, ...rest]
+    for (const key of Object.keys(value)) {
+      result[key] = transformValue(value[key], leafSerializer)
     }
+
+    return result
   }
 
-  return value
+  // Encode non-JSON leaf values (Date, RegExp, BigInt, etc.)
+  return ['leaf', leafSerializer(value)]
 }
 
-export default function stringify (program) {
-  return JSON.stringify(program, replacer)
+export default function stringify (program, leafSerializer = JSON.stringify) {
+  return JSON.stringify(transformValue(program, leafSerializer))
 }