sendscript 1.0.6 → 2.0.1

package/.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: Publish Package
 on:
   push:
     tags:
-      - 'v*'
+      - '*'
 
 permissions:
   id-token: write  # Required for OIDC
@@ -22,4 +22,4 @@ jobs:
       - run: npm ci
       - run: npm run build --if-present
       - run: npm test
-      - run: npm publish
+      - run: npm publish

package/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release on tag
+
+on:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  contents: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: ['lts/*', 'latest']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - run: npm ci
+      - run: npm test
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 'latest'
+          cache: npm
+
+      - run: npm ci
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

package/CHANGELOG.md

@@ -4,8 +4,30 @@ 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.0.1](https://github.com/bas080/sendscript/compare/v2.0.0...v2.0.1)
+
+- Publish to npm on tag push [`357ac0e`](https://github.com/bas080/sendscript/commit/357ac0ef3384f294e4f9bb179d5a675afda5fd19)
+
+### [v2.0.0](https://github.com/bas080/sendscript/compare/v1.1.0...v2.0.0)
+
+> 8 April 2026
+
+- Rewrite to have parse take schema to prevent accessing refs [`df16f85`](https://github.com/bas080/sendscript/commit/df16f85c79299aa8bcd3e44b6cc127bd7198eace)
+- Run tests before release and publish on release [`10442d6`](https://github.com/bas080/sendscript/commit/10442d6766a098926ee98daee08dba23eea0fb14)
+- Create release on tag with github workflows [`4ec222b`](https://github.com/bas080/sendscript/commit/4ec222bf51fc1d3cce9fc54fdd1e9639b5d259cd)
+
+#### [v1.1.0](https://github.com/bas080/sendscript/compare/v1.0.6...v1.1.0)
+
+> 7 April 2026
+
+- 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)
 

package/README.md

@@ -17,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)
@@ -47,15 +53,16 @@ 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'
+import Stringify from 'sendscript/stringify.mjs'
+import references from 'sendscript/references.mjs'
 
-const { add } = module(['add'])
+const { add } = references(['add'])
+const stringify = Stringify()
 
 console.log(stringify(add(1,2)))
 ```
 ```json
-["call",["ref","add"],[1,2]]
+["call",["ref","add"],[["leaf","1"],["leaf","2"]]]
 ```
 
 We can then parse that JSON and it will evaluate down to a value.
@@ -69,7 +76,7 @@ const module = {
   }
 }
 
-const parse = Parse(module)
+const parse = Parse(['add'], module)
 
 const program = '["call",["ref","add"],[1,2]]'
 
@@ -125,7 +132,8 @@ import { Server } from 'socket.io'
 import Parse from 'sendscript/parse.mjs'
 import * as math from './math.mjs'
 
-const parse = Parse(math)
+const schema = Object.keys(math)
+const parse = Parse(schema, math)
 const server = new Server()
 const port = process.env.PORT || 3000
 
@@ -152,11 +160,13 @@ Now for a client that sends a program to the server.
 // ./example/client.socket.io.mjs
 
 import socketClient from 'socket.io-client'
-import stringify from 'sendscript/stringify.mjs'
-import module from 'sendscript/module.mjs'
-import * as math from './math.mjs'
+import Stringify from 'sendscript/stringify.mjs'
+import references from 'sendscript/references.mjs'
 import assert from 'node:assert'
 
+const { add, square } = references(['add', 'square'])
+const stringify = Stringify()
+
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
 
@@ -170,8 +180,6 @@ const send = program => {
   })
 }
 
-const { add, square } = module(math)
-
 // The program to be sent over the wire
 const program = square(add(1, add(add(2, 3), 4)))
 
@@ -247,52 +255,31 @@ export const add = (a: number, b: number) => a + b
 export const square = (a: number) => a * a
 ```
 
-We want to use this module on the client. We create a client version of that module and coerce the types to match those of the server.
-
-```bash
-cat ./example/typescript/math.client.ts
-```
-```ts
-import module from 'sendscript/module.mjs'
-import type * as mathTypes from './math.ts'
-
-const math = module([
-  'add',
-  'square'
-]) as typeof mathTypes
-
-export default math
-```
-
-We now use the client version of this module.
+We can then coerce the types of the instrumented stubs.
 
 ```bash
 cat ./example/typescript/client.ts
 ```
 ```ts
-import stringify from 'sendscript/stringify.mjs'
+import math  from './math.client.ts'
+import Stringify from 'sendscript/stringify.mjs'
 
-async function send<T>(program: T): Promise<T>{
+const stringify = Stringify()
+
+// The return type of this function matches the type passed as the return of the program.
+async function send<T>(program: T): Promise<T> {
   return (await fetch('/api', {
     method: 'POST',
     body: stringify(program)
   })).json()
 }
 
-import math from './math.client.ts'
-
-const { add, square } = math
-
 send(square(add(1, 2)))
 ```
 
 We'll also generate the docs for this module.
 
 ```bash
-npm install --no-save \
-  typedoc \
-  typedoc-plugin-markdown
-
 npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
 ```
 
@@ -303,6 +290,135 @@ 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 **an array of function names**
+
+```js
+
+const schema = [
+  'help',
+  'version',
+
+  ['math', [
+    'add',
+    'sub'
+  ]],
+  ['vector', [
+    'add',
+    'multiply'
+  ]],
+  ['utils', [
+    'identity',
+    'always'
+  ]],
+})
+```
+
+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)
+  )
+)
+```
+
+## 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 references from 'sendscript/references.mjs'
+import Parse from 'sendscript/parse.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 schema = ['processData']
+
+const { processData } = references(schema)
+const stringify = Stringify(leafSerializer)
+
+// 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))
+
+// The environment
+const env = {
+  processData: (data) => ({
+    success: true,
+    received: data
+  })
+}
+
+// Parse with custom leaf deserializer
+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.
@@ -313,19 +429,19 @@ npm t -- report text-summary
 ```
 ```
 
-> sendscript@1.0.6 test
+> sendscript@2.0.1 test
 > tap -R silent
 
 
-> sendscript@1.0.6 test
+> sendscript@2.0.1 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% ( 348/348 )
+Branches     : 100% ( 145/145 )
+Functions    : 100% ( 24/24 )
+Lines        : 100% ( 348/348 )
 ================================================================================
 ```
 

package/README.mz

@@ -30,10 +30,11 @@ 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'
+import Stringify from 'sendscript/stringify.mjs'
+import references from 'sendscript/references.mjs'
 
-const { add } = module(['add'])
+const { add } = references(['add'])
+const stringify = Stringify()
 
 console.log(stringify(add(1,2)))
 ```
@@ -49,7 +50,7 @@ const module = {
   }
 }
 
-const parse = Parse(module)
+const parse = Parse(['add'], module)
 
 const program = '["call",["ref","add"],[1,2]]'
 
@@ -102,7 +103,8 @@ import { Server } from 'socket.io'
 import Parse from 'sendscript/parse.mjs'
 import * as math from './math.mjs'
 
-const parse = Parse(math)
+const schema = Object.keys(math)
+const parse = Parse(schema, math)
 const server = new Server()
 const port = process.env.PORT || 3000
 
@@ -129,11 +131,13 @@ Now for a client that sends a program to the server.
 // ./example/client.socket.io.mjs
 
 import socketClient from 'socket.io-client'
-import stringify from 'sendscript/stringify.mjs'
-import module from 'sendscript/module.mjs'
-import * as math from './math.mjs'
+import Stringify from 'sendscript/stringify.mjs'
+import references from 'sendscript/references.mjs'
 import assert from 'node:assert'
 
+const { add, square } = references(['add', 'square'])
+const stringify = Stringify()
+
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
 
@@ -147,8 +151,6 @@ const send = program => {
   })
 }
 
-const { add, square } = module(math)
-
 // The program to be sent over the wire
 const program = square(add(1, add(add(2, 3), 4)))
 
@@ -217,13 +219,7 @@ Let's say we have this module which we use on the server.
 cat ./example/typescript/math.ts
 ```
 
-We want to use this module on the client. We create a client version of that module and coerce the types to match those of the server.
-
-```bash|ts bash
-cat ./example/typescript/math.client.ts
-```
-
-We now use the client version of this module.
+We can then coerce the types of the instrumented stubs.
 
 ```bash|ts bash
 cat ./example/typescript/client.ts
@@ -232,10 +228,6 @@ cat ./example/typescript/client.ts
 We'll also generate the docs for this module.
 
 ```bash bash 1>&2
-npm install --no-save \
-  typedoc \
-  typedoc-plugin-markdown
-
 npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
 ```
 
@@ -246,6 +238,135 @@ 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 **an array of function names**
+
+```js
+
+const schema = [
+  'help',
+  'version',
+
+  ['math', [
+    'add',
+    'sub'
+  ]],
+  ['vector', [
+    'add',
+    'multiply'
+  ]],
+  ['utils', [
+    'identity',
+    'always'
+  ]],
+})
+```
+
+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)
+  )
+)
+```
+
+## 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 references from 'sendscript/references.mjs'
+import Parse from 'sendscript/parse.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 schema = ['processData']
+
+const { processData } = references(schema)
+const stringify = Stringify(leafSerializer)
+
+// 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))
+
+// The environment
+const env = {
+  processData: (data) => ({
+    success: true,
+    received: data
+  })
+}
+
+// Parse with custom leaf deserializer
+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.

package/example/client.socket.io.mjs

@@ -1,11 +1,13 @@
 // ./example/client.socket.io.mjs
 
 import socketClient from 'socket.io-client'
-import stringify from 'sendscript/stringify.mjs'
-import module from 'sendscript/module.mjs'
-import * as math from './math.mjs'
+import Stringify from 'sendscript/stringify.mjs'
+import references from 'sendscript/references.mjs'
 import assert from 'node:assert'
 
+const { add, square } = references(['add', 'square'])
+const stringify = Stringify()
+
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
 
@@ -19,8 +21,6 @@ const send = program => {
   })
 }
 
-const { add, square } = module(math)
-
 // The program to be sent over the wire
 const program = square(add(1, add(add(2, 3), 4)))
 

package/example/server.socket.io.mjs

@@ -4,7 +4,8 @@ import { Server } from 'socket.io'
 import Parse from 'sendscript/parse.mjs'
 import * as math from './math.mjs'
 
-const parse = Parse(math)
+const schema = Object.keys(math)
+const parse = Parse(schema, math)
 const server = new Server()
 const port = process.env.PORT || 3000
 

package/example/typescript/client.ts

@@ -1,14 +1,14 @@
-import stringify from 'sendscript/stringify.mjs'
+import math  from './math.client.ts'
+import Stringify from 'sendscript/stringify.mjs'
 
-async function send<T>(program: T): Promise<T>{
+const stringify = Stringify()
+
+// The return type of this function matches the type passed as the return of the program.
+async function send<T>(program: T): Promise<T> {
   return (await fetch('/api', {
     method: 'POST',
     body: stringify(program)
   })).json()
 }
 
-import math from './math.client.ts'
-
-const { add, square } = math
-
 send(square(add(1, 2)))

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