SendScript

Write JS code that you can run on servers, browsers or other clients.

• Introduction
• Reference
  • defaultLeafParse
  • Parse
  • parse
  • References
  • SchemaNode
  • Schema
  • defaultLeafStringify
  • Stringify
  • stringify
• Socket example
  • Module
  • Server
  • Client
• Repl
• Functions
• Promises
  • .then / .catch
  • await
• TypeScript
• Schema and Nested Modules
  • Defining a Nested Module
• Validation (using Zod)
  • Validating structured input
• Leaf Serializer
  • Example with superjson
• Changelog
• License
• Issues

Introduction

There has been interest in improving APIs by allowing aggregations in a single request. Examples include

• JSON-RPC 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 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.

import Stringify from 'sendscript/stringify.mjs'
import references from 'sendscript/references.mjs'

const { add } = references(['add'])
const stringify = Stringify()

console.log(stringify(add(1,2)))

["call",["ref","add"],[["leaf","1"],["leaf","2"]]]

We can then parse that JSON and it will evaluate down to a value.

import Parse from 'sendscript/parse.mjs'

const module = {
  add(a, b) {
    return a + b
  }
}

const parse = Parse(['add'], module)

const program = '["call",["ref","add"],[1,2]]'

console.log(parse(program))

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 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.

Reference

defaultLeafParse

parse.mjs:49-49

Default deserializer for leaf nodes.

Parameters

• text string

Returns any

Parse

parse.mjs:68-215

Parameters

• schema Schema
• env Env runtime environment for refs
• leafParse (optional, default defaultLeafParse)

Returns parse

parse

parse.mjs:78-214

Parses and executes a serialized program.

Parameters

• program string JSON encoded program

Returns (any | Promise<any>)

References

references.mjs:109-127

Builds a nested API structure from a schema definition.

Parameters

• schema Schema
• parentPath (optional, default [])

• Throws Error If schema format is invalid

Returns Object Nested instrumented API object

SchemaNode

schema.mjs:1-19

A single schema node.

Type: (string | [string, Schema])

Schema

schema.mjs:1-19

A schema defines the structure of the runtime API tree.

• string → leaf node
• [name, children] → namespace node

Schema is recursive: nodes can contain nested schemas.

Type: Array<SchemaNode>

defaultLeafStringify

stringify.mjs:37-47

Default strict serializer for leaf values.

Rejects non-JSON-safe values.

Parameters

• x any

Returns string

Stringify

stringify.mjs:56-157

Creates a stringify function for SendScript AST structures.

Parameters

• leafStringify (optional, default defaultLeafStringify)

Returns stringify

stringify

stringify.mjs:64-156

Serializes a program into a JSON string representation.

Parameters

• program any

Returns string

Socket example

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.

For this example we'll use socket.io.

Module

We write a simple module.

// ./example/math.mjs

export const add = (a, b) => a + b
export const square = (a) => a * a

Server

Here a socket.io server that runs SendScript programs.

// ./example/server.socket.io.mjs

import { Server } from 'socket.io'
import Parse from 'sendscript/parse.mjs'
import * as math from './math.mjs'

const schema = Object.keys(math)
const parse = Parse(schema, math)
const server = new Server()
const port = process.env.PORT || 3000

server.on('connection', (socket) => {
  socket.on('message', async (program, callback) => {
    try {
      const result = parse(program)
      callback(null, result) // Pass null as the first argument to indicate success
    } catch (error) {
      callback(error) // Pass the error to the callback
    }
  })
})

server.listen(port)
process.title = 'sendscript'

Client

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 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}`)

const send = (program) => {
  return new Promise((resolve, reject) => {
    client.emit('message', stringify(program), (error, result) => {
      error ? reject(error) : resolve(result)
    })
  })
}

// The program to be sent over the wire
const program = square(add(1, add(add(2, 3), 4)))

const result = await send(program)

console.log('Result: ', result)

assert.equal(result, 100)

process.exit(0)

Now we run this server and a client script.

set -e

# Run the server
node ./example/server.socket.io.mjs&

# Run the client example
node ./example/client.socket.io.mjs

pkill sendscript

Result:  100

Repl

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.

Functions

SendScript as of v2.4 supports functions to do basic templating. It does not support async functions and will throw an error when you define one.

Under the hood the function is called when it is being parsed. Make sure you understand what you are doing when mixing client and server functions.

map((a) => add(a, 1))([1, 2, 3]))

It also supports nested functions.

map(call)(map((a) => () => add(a, 1))([1, 2, 3]))

Promises

.then / .catch

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.

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.

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.

const userId = 'user-123'
const program = {
  unread: await fetchUnreadMessages(userId),
  emptyTrash: await emptyTrash(userId),
  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.

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 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.

cat ./example/typescript/math.ts

export const add = (a: number, b: number) => a + b
export const square = (a: number) => a * a

We can then coerce the types of the instrumented stubs.

cat ./example/typescript/client.ts

import math  from './math.client.ts'
import Stringify from 'sendscript/stringify.mjs'

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()
}

send(square(add(1, 2)))

We'll also generate the docs for this module.

npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts

You can see the docs here

[!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.

Defining a Nested Module

You can define a schema as an array of function names

const schema = [
  'help',
  'version',

  ['math', [
    'add',
    'sub'
  ]],
  ['vector', [
    'add',
    'multiply'
  ]],
  ['utils', [
    'identity',
    'always'
  ]],
})

Functions are referenced via their path in the module tree:

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.

Validating structured input

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 to support extended types:

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.

Changelog

The changelog is generated using the useful auto-changelog project.

npx auto-changelog -p

License

See the LICENSE.txt file for details.

Issues

See issues for roadmap and known bugs.