README.mz

# SendScript

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

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

<!-- toc -->

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.

## Socket example

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.

```js cat - > ./example/math.mjs
// ./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 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 parse = Parse(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 module from 'sendscript/module.mjs'
import * as math from './math.mjs'
import assert from 'node:assert'

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

const { add, square } = module(math)

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

## Async/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|ts bash
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.

```bash|ts bash
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

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.

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

## Dependencies

Check if packages are up to date on release.

```bash bash
npm outdated && echo 'No outdated packages found'
```

## License

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

## Roadmap

- [ ] Support for simple lambdas to compose functions more easily.

[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