README.mz

# SendScript

Serialize and execute composable JavaScript function calls with JSON.

[![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)
[![Stand with Palestine](https://img.shields.io/badge/🇵🇸%20%20Stand%20With%20Palestine-007A3D?style=flat-square&color=brightgreen)](https://www.islamic-relief.org.uk/giving/appeals/palestine/)

## Features

- **Composable function calls** - Combine multiple functions into a single
  request
- **Write ordinary JavaScript** - Programs serialize to JSON and execute as
  written
- **Type-safe** - Works great with TypeScript for client-side type checking
- **Zero dependencies** - Lightweight core library
- **Async/await support** - Seamless async operations within a single payload
- **Custom serializers** - Support for Date, Map, Set, BigInt, and more
- **Transport agnostic** - Use HTTP, WebSockets, or any other communication
  method

<!-- toc -->

## Installation

Install SendScript from npm:

```bash
npm install sendscript
```

## Quick Start

Here's the simplest example to get started with SendScript:

```js
import Stringify from 'sendscript/stringify.mjs'
import Parse from 'sendscript/parse.mjs'
import references from 'sendscript/references.mjs'

// Define your functions
const functions = {
  greet: (name) => `Hello, ${name}!`,
}

// Create client-side stubs
const { greet } = references(['greet'])

// Serialize a program on the client
const stringify = Stringify()
const program = stringify(greet('World'))

// Parse and execute on the server
const parse = Parse(['greet'], functions)
const result = parse(program) // "Hello, World!"
```

This demonstrates the core concept: write a program on the client, serialize it
to JSON, send it to the server, and execute it exactly as written.

## 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
  language and the tooling that is required to wield it.

## Why SendScript?

Unlike JSON-RPC (which doesn't support function composition) or GraphQL (which
requires learning a new language), SendScript lets you write ordinary
JavaScript/TypeScript that gets serialized and executed on the server exactly as
written.

## How It Works

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 references from 'sendscript/references.mjs'

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

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(['add'], 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 `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.

> **Note:** SendScript works in Node.js and browsers. The core library is
> framework-agnostic and transport-agnostic — use HTTP, WebSockets, or any other
> communication method that suits your needs.

Future enhancements may include support for more complex (de)serializers,
improved error handling, and deeper integration of client functions with
SendScript programs. Contributions and feedback are welcome.

## 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][socket.io].

### Module

We write a simple module.

```js cat - > ./example/math.mjs
// ./example/math.mjs

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

### Server

Here's a socket.io server that runs SendScript programs.

```js cat - > ./example/server.socket.io.mjs
// ./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.

```js cat - > ./example/client.socket.io.mjs
// ./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.

```bash bash
set -e

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

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

pkill sendscript
```

## Repl

Sendscript ships with a bare-bones (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 printing
> only sendscript logs.

## Promises

### .then / .catch

Supported since `v2.3`.

```js
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

By default, `await api.someMethod(...)` still creates a SendScript await stub
and keeps the result serializable with `stringify()`. It does not automatically
send anything over the network.

```js
const api = references(['add'])
const program = api.add(1, 2)

Stringify()(program)
// => "[\"call\",[\"ref\",\"add\"],[1,2]]"
```

If you want native `await` to cross the transport boundary, pass an `onAwait`
handler when creating the references:

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

const stringify = Stringify()

const api = references(['add'], (program) => {
  return fetch('/api', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: stringify(program),
  }).then((response) => response.json())
})

const result = await api.add(1, 2)
```

The callback receives the generated SendScript program, and you decide how it is
transported or executed.

## TypeScript

Using SendScript with TypeScript enables **type-safe client-side code**. Your
client can have full IDE autocomplete and compile-time type checking when
calling server functions.

### Server-Side Module

Define your API as a TypeScript module on the server:

```bash|ts bash
cat ./example/typescript/math.ts
```

### Client-Side Type Stub

Create a client-side file that mirrors your server types using the `as typeof`
casting pattern:

```bash|ts bash
cat ./example/typescript/math.client.ts
```

The `as typeof mathTypes` type assertion gives your client-side references the
exact same types as your server module. This means:

- Full IDE autocomplete for function names and parameters
- Compile-time type checking - catch errors before runtime
- Your client code looks identical to regular JavaScript calls

### Using Typed References

Now on your client, you have complete type safety:

```bash|ts bash
cat ./example/typescript/client.ts
```

TypeScript knows the exact parameter types and return types for every function
call.

### Generating API Documentation

You can use [typedoc][typedoc] to automatically generate documentation from your
TypeScript types:

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

This generates markdown docs that can be shared with API consumers. See the
[generated docs](./example/typescript/docs/globals.md).

> [!IMPORTANT] **Type vs. Runtime Values**
>
> Type casting on the client side improves the development experience, but
> remember:
>
> - The actual serialized JSON may differ from the static types
> - Runtime values depend on serialization/deserialization
> - Always validate user input on the server using schema validation (e.g., Zod)
> - Use the types as a contract, not a guarantee

## 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, leafDeserializer)

const result = parse(json)
```

The leaf wrapper format is `['leaf', serializedPayload]`, making it unambiguous
and safe from colliding with SendScript operators.

## Limitations

The stubs the `references` function returns are limited in the way they can be
used. This has to do with the fact that they are to be serialized.

### Chaining APIs

Currently you cannot do chaining APIs. `lib().doThis().doThat()`. It likely is
possible to implement but will require more extensive schemas and obviously more
code to create the AST.

### Callbacks

SendScript supports basic callback-style usage, such as passing a function as an
argument or using a callback to flip arguments into the generated program.

```js
const api = references(['map', 'add'])

const result = api.map((value) => api.add(value, 1))([1, 2, 3])
```

This is meant for composing SendScript programs, not for executing arbitrary
client-side logic at runtime.

> [!WARNING] Mixing client and server functions can be confusing, because the
> callback may be used to build a program rather than execute immediately. Keep
> callback logic simple and deterministic.

### Error handling

Sendscript does not have builtin tools to handle errors. You can write your own
utilities for that or use things like [Ramda's tryCatch][tryCatch]. This will
likely never be supported as JS try catch does not have a return value. It might
make sense to wrap everything that can throw in promises which is easy to do
with async functions.

## Tests

Tests with 100% code coverage.

```bash bash
npm t -- -R silent
npm t -- report text-summary
```

## Formatting

Standard because no config.

```bash bash
npx standard
```

## Changelog

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

```bash bash > /dev/null
npx auto-changelog -p
```

## License

See the [LICENSE.txt][license] file for details.

## Issues

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