https://github.com/bas080/sendscript
RPC and no-build with composable function calls in a single payload.
https://github.com/bas080/sendscript
client-server json lisp rpc
Last synced: about 1 hour ago
JSON representation
RPC and no-build with composable function calls in a single payload.
- Host: GitHub
- URL: https://github.com/bas080/sendscript
- Owner: bas080
- License: mit
- Created: 2023-09-14T00:03:25.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2026-04-14T17:30:27.000Z (about 4 hours ago)
- Last Synced: 2026-04-14T19:10:11.616Z (about 3 hours ago)
- Topics: client-server, json, lisp, rpc
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/sendscript
- Size: 388 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# SendScript
Write JS code that you can run on servers, browsers or other clients.
[](https://www.npmjs.com/package/sendscript)
[](#tests)
[](https://standardjs.com)
[](./LICENSE.txt)
- [Introduction](#introduction)
- [Reference](#reference)
* [defaultLeafParse](#defaultleafparse)
* [Parse](#parse)
* [parse](#parse)
* [References](#references)
* [SchemaNode](#schemanode)
* [Schema](#schema)
* [defaultLeafStringify](#defaultleafstringify)
* [Stringify](#stringify)
* [stringify](#stringify)
- [Socket example](#socket-example)
* [Module](#module)
* [Server](#server)
* [Client](#client)
- [Repl](#repl)
- [Promises](#promises)
* [.then / .catch](#then--catch)
* [await](#await)
- [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)
- [Changelog](#changelog)
- [License](#license)
- [Issues](#issues)
## 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 references from 'sendscript/references.mjs'
const { add } = references(['add'])
const stringify = Stringify()
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(['add'], 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 `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
### defaultLeafParse
Default deserializer for leaf nodes.
#### Parameters
* `text` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
Returns **any**
### Parse
#### Parameters
* `schema` **[Schema](#schema)**
* `env` **Env** runtime environment for refs
* `leafParse` (optional, default `defaultLeafParse`)
Returns **[parse](#parse)**
### 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)\)**
### References
Builds a nested API structure from a schema definition.
#### Parameters
* `schema` **[Schema](#schema)**
* `parentPath` (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
### SchemaNode
A single schema node.
Type: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | \[[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), [Schema](#schema)])
### Schema
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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[SchemaNode](#schemanode)>
### defaultLeafStringify
Default strict serializer for leaf values.
Rejects non-JSON-safe values.
#### Parameters
* `x` **any**
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
### Stringify
Creates a stringify function for SendScript AST structures.
#### Parameters
* `leafStringify` (optional, default `defaultLeafStringify`)
Returns **[stringify](#stringify)**
### stringify
Serializes a program into a JSON string representation.
#### Parameters
* `program` **any**
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
## Socket example
For this example we'll use [socket.io][socket.io].
### Module
We write a simple module.
```js
// ./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.
```js
// ./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
// ./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
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.
## Promises
### .then / .catch
Supported since vs `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
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.
```js
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][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
```
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'
const stringify = Stringify()
// The return type of this function matches the type passed as the return of the program.
async function send(program: T): Promise {
return (await fetch('/api', {
method: 'POST',
body: stringify(program)
})).json()
}
send(square(add(1, 2)))
```
We'll also generate the docs for this module.
```bash
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)
> \[!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**
```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.
## Changelog
The [changelog][changelog] is generated using the useful
[auto-changelog][auto-changelog] project.
```bash
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