sendscript 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -4,7 +4,20 @@ 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).
 
-#### [v1.0.0](https://github.com/bas080/sendscript/compare/v0.1.4...v1.0.0)
+#### [v1.0.2](https://github.com/bas080/sendscript/compare/v1.0.1...v1.0.2)
+
+- Improve the typescript example [`6f75ed6`](https://github.com/bas080/sendscript/commit/6f75ed6a4b4db94217fde41ae50bc6b92a2cffda)
+- Move errors to own module [`90d69a3`](https://github.com/bas080/sendscript/commit/90d69a337f92518c8dd5c2ad47dd9b1add80d0c3)
+
+#### [v1.0.1](https://github.com/bas080/sendscript/compare/v1.0.0...v1.0.1)
+
+> 3 May 2025
+
+- Add async await section to readme [`7e56024`](https://github.com/bas080/sendscript/commit/7e560246e2a7b5b34f1de0ce5eb0df62897cc454)
+
+### [v1.0.0](https://github.com/bas080/sendscript/compare/v0.1.4...v1.0.0)
+
+> 3 May 2025
 
 - Add support for async await [`e949184`](https://github.com/bas080/sendscript/commit/e949184ab31a3bfdf4c6181463dcdd7250aca3a8)
 - Update tap to latest version on 2024-03-17 [`1164994`](https://github.com/bas080/sendscript/commit/11649947737ffd152ac46d1db01946ad0c1261e7)

package/README.md

@@ -13,6 +13,7 @@ Write JS code that you can run on servers, browsers or other clients.
   * [Module](#module)
   * [Server](#server)
   * [Client](#client)
+- [Async/Await](#asyncawait)
 - [TypeScript](#typescript)
 - [Tests](#tests)
 - [Formatting](#formatting)
@@ -135,6 +136,25 @@ pkill sendscript
 Result:  100
 ```
 
+## 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.
@@ -146,24 +166,67 @@ There is a good use-case to write a module in TypeScript.
 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
-# Create pretty docs for your module.
-npx typedoc my-module.ts
+cat ./example/typescript/math.ts
+```
+```ts
+export const add = (a: number, b: number) => a + b
+export const square = (a: number) => a * a
 ```
 
-Now we can use the `my-module.ts` file for the client API.
+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 type * as MyModule from './my-module'
+import module from 'sendscript/module.mjs'
+import type * as mathTypes from './math.ts'
 
-import sendScriptApi from 'sendscript/api.mjs'
+const math = module([
+  'add',
+  'square'
+]) as typeof mathTypes
 
-export default sendScriptApi([
-  fnOne,
-  fnTwo,
-], /* perform websocket request */) as typeof MyModule
+export default math
 ```
 
+We now use the client version of this module.
+
+```bash
+cat ./example/typescript/client.ts
+```
+```ts
+import stringify from 'sendscript/stringify.mjs'
+
+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
+typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
+```
+```
+[info] Loaded plugin typedoc-plugin-markdown
+[info] markdown generated at ./example/typescript/docs
+```
+
+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.
@@ -179,19 +242,19 @@ npm t -- report text-summary
 ```
 ```
 
-> sendscript@1.0.0 test
+> sendscript@1.0.2 test
 > tap -R silent
 
 
-> sendscript@1.0.0 test
+> sendscript@1.0.2 test
 > tap report text-summary
 
 
 =============================== Coverage summary ===============================
-Statements   : 100% ( 239/239 )
-Branches     : 100% ( 71/71 )
+Statements   : 100% ( 245/245 )
+Branches     : 100% ( 74/74 )
 Functions    : 100% ( 18/18 )
-Lines        : 100% ( 239/239 )
+Lines        : 100% ( 245/245 )
 ================================================================================
 ```
 

package/README.mz

@@ -118,6 +118,25 @@ node ./example/client.socket.io.mjs
 pkill sendscript
 ```
 
+## 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.
@@ -129,24 +148,32 @@ There is a good use-case to write a module in TypeScript.
 3. You can use the types of the module to coerce your client to adopt the
    module's type.
 
-```bash
-# Create pretty docs for your module.
-npx typedoc my-module.ts
+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
 ```
 
-Now we can use the `my-module.ts` file for the client API.
+We now use the client version of this module.
 
-```ts
-import type * as MyModule from './my-module'
+```bash|ts bash
+cat ./example/typescript/client.ts
+```
 
-import sendScriptApi from 'sendscript/api.mjs'
+We'll also generate the docs for this module.
 
-export default sendScriptApi([
-  fnOne,
-  fnTwo,
-], /* perform websocket request */) as typeof MyModule
+```bash bash
+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.

package/error.mjs

@@ -1,9 +1,2 @@
-class BlendError extends Error { }
-class BlendExpressionError extends BlendError {}
-class BlendInvalidSchemaError extends BlendError {}
-
-export {
-  BlendError,
-  BlendExpressionError,
-  BlendInvalidSchemaError
-}
+export class SendScriptError extends Error {}
+export class SendScriptReferenceError extends SendScriptError {}

package/example/typescript/client.ts

@@ -0,0 +1,14 @@
+import stringify from 'sendscript/stringify.mjs'
+
+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/README.md

@@ -0,0 +1,207 @@
+**sendscript**
+
+***
+
+# 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
+npm install --no-save socket.io socket.io-client
+```
+
+> We use the `--no-save` option because it's only for demonstration purposes.
+
+### 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 '../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
+// ./example/client.socket.io.mjs
+
+import socketClient from 'socket.io-client'
+import stringify from '../stringify.mjs'
+import module from '../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
+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
+```
+
+## 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
+cat ./example/typescript/math.ts
+```
+```ts
+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.
+
+```bash
+cat ./example/typescript/client.ts
+```
+```ts
+import stringify from 'sendscript/stringify.mjs'
+
+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.

package/example/typescript/docs/functions/add.md

@@ -0,0 +1,25 @@
+[**sendscript**](../README.md)
+
+***
+
+[sendscript](../globals.md) / add
+
+# Function: add()
+
+> **add**(`a`, `b`): `number`
+
+Defined in: [math.ts:1](https://github.com/bas080/sendscript/blob/6f75ed6a4b4db94217fde41ae50bc6b92a2cffda/example/typescript/math.ts#L1)
+
+## Parameters
+
+### a
+
+`number`
+
+### b
+
+`number`
+
+## Returns
+
+`number`

package/example/typescript/docs/functions/square.md

@@ -0,0 +1,21 @@
+[**sendscript**](../README.md)
+
+***
+
+[sendscript](../globals.md) / square
+
+# Function: square()
+
+> **square**(`a`): `number`
+
+Defined in: [math.ts:2](https://github.com/bas080/sendscript/blob/6f75ed6a4b4db94217fde41ae50bc6b92a2cffda/example/typescript/math.ts#L2)
+
+## Parameters
+
+### a
+
+`number`
+
+## Returns
+
+`number`

package/example/typescript/docs/globals.md

@@ -0,0 +1,10 @@
+[**sendscript**](README.md)
+
+***
+
+# sendscript
+
+## Functions
+
+- [add](functions/add.md)
+- [square](functions/square.md)

package/example/typescript/math.client.ts

@@ -0,0 +1,9 @@
+import module from 'sendscript/module.mjs'
+import type * as mathTypes from './math.ts'
+
+const math = module([
+  'add',
+  'square'
+]) as typeof mathTypes
+
+export default math

package/example/typescript/math.ts

@@ -0,0 +1,2 @@
+export const add = (a: number, b: number) => a + b
+export const square = (a: number) => a * a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sendscript",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Blur the line between server and client code.",
   "module": true,
   "main": "index.mjs",

package/parse.mjs

@@ -1,8 +1,6 @@
 import Debug from './debug.mjs'
 import isNil from './is-nil.mjs'
-
-class SendScriptError extends Error {}
-class SendScriptReferenceError extends SendScriptError {}
+import { SendScriptReferenceError } from './error.mjs'
 
 const debug = Debug.extend('parse')
 
@@ -14,13 +12,19 @@ export default (env) =>
     const resolved = {}
 
     JSON.parse(program, (key, value) => {
-      if (Array.isArray(value) && value[0] === 'await') {
-        awaits.push(((program, awaitId) => async () => {
-          const value = await JSON.parse(JSON.stringify(program), reviver)
-          resolved[awaitId] = value
+      if (!Array.isArray(value)) return value
+
+      const [operator, ...rest] = value
 
-          debug('awaits', awaits)
-        })(value[1], value[2]))
+      if (operator === 'await') {
+        const [program, awaitId] = rest
+
+        awaits.push(((program, awaitId) => async () => {
+          resolved[awaitId] = await JSON.parse(
+            JSON.stringify(program),
+            reviver
+          )
+        })(program, awaitId))
       }
 
       return value