sendscript 2.4.2 → 2.5.0

package/CHANGELOG.md

@@ -4,8 +4,21 @@ 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).
 
+#### [v2.5.0](https://github.com/bas080/sendscript/compare/v2.4.3...v2.5.0)
+
+- Clarify native await behavior in README [`a26f1b3`](https://github.com/bas080/sendscript/commit/a26f1b3c204390690eda7950c967d31ee55aa353)
+- Allow passing onAwait callback to references make function [`8fdb1c4`](https://github.com/bas080/sendscript/commit/8fdb1c4bfa0682fabdd9d27ca075cd1e0cfaedf7)
+
+#### [v2.4.3](https://github.com/bas080/sendscript/compare/v2.4.2...v2.4.3)
+
+> 17 August 2026
+
+- Improve TypeScript section with comprehensive examples and explanations [`a3c5867`](https://github.com/bas080/sendscript/commit/a3c5867f835bbcde1e802e75c80ca6f02dd4f0e8)
+
 #### [v2.4.2](https://github.com/bas080/sendscript/compare/v2.4.1...v2.4.2)
 
+> 17 August 2026
+
 - Update tap and typedoc [`46421de`](https://github.com/bas080/sendscript/commit/46421de16533066ee13c91ea75505b1ecdd548f0)
 - Remove the unused curry helper [`9dcbb48`](https://github.com/bas080/sendscript/commit/9dcbb485b455937070c65359ecde8236c128bee8)
 - Remove duplicate Promises section with outdated async/await information [`5f43ddb`](https://github.com/bas080/sendscript/commit/5f43ddb91ddb2d77227ddd6a570807f874230ea1)

package/README.md

@@ -36,6 +36,10 @@ Serialize and execute composable JavaScript function calls with JSON.
   * [.then / .catch](#then--catch)
   * [await](#await)
 - [TypeScript](#typescript)
+  * [Server-Side Module](#server-side-module)
+  * [Client-Side Type Stub](#client-side-type-stub)
+  * [Using Typed References](#using-typed-references)
+  * [Generating API Documentation](#generating-api-documentation)
 - [Schema and Nested Modules](#schema-and-nested-modules)
   * [Defining a Nested Module](#defining-a-nested-module)
 - [Validation (using Zod)](#validation-using-zod)
@@ -302,61 +306,121 @@ 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.
+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.
 
-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 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
-const userId = 'user-123'
-const program = {
-  unread: await fetchUnreadMessages(userId),
-  emptyTrash: await emptyTrash(userId),
-  archived: await archiveMessages(selectMessages({ old: true })),
-}
+import Stringify from 'sendscript/stringify.mjs'
+import references from 'sendscript/references.mjs'
 
-const result = await send(program)
+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)
 ```
 
-This operation is done in a single round-trip. The result is an object with the
-defined properties and returned values.
+The callback receives the generated SendScript program, and you decide how it is
+transported or executed.
 
 ## TypeScript
 
-There is a good use-case to write a module in 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.
 
-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.
+### Server-Side Module
 
-Let's say we have this module which we use on the server.
+Define your API as a TypeScript module 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
+/**
+ * Server-side math module with typed functions
+ * These functions will be called from the client through SendScript
+ */
+
+export const add = (a: number, b: number): number => a + b
+
+export const square = (a: number): number => a * a
+
 ```
 
-We can then coerce the types of the instrumented stubs.
+### Client-Side Type Stub
+
+Create a client-side file that mirrors your server types using the `as typeof`
+casting pattern:
+
+```bash
+cat ./example/typescript/math.client.ts
+```
+```ts
+/**
+ * Client-side type-safe stubs for the math API
+ * 
+ * This file creates typed references that mirror the server's functions.
+ * The 'as typeof mathTypes' cast gives us full TypeScript support and IDE autocomplete.
+ */
+
+import type * as mathTypes from './math.ts'
+import references from 'sendscript/references.mjs'
+
+// Create type-safe stubs - this tells TypeScript that 'add' and 'square' 
+// have the same signatures as the server functions
+export default references(['add', 'square']) as typeof mathTypes
+
+```
+
+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
 cat ./example/typescript/client.ts
 ```
 ```ts
-import math  from './math.client.ts'
+/**
+ * Client-side usage with type-safe SendScript
+ */
+
+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.
+/**
+ * Send a SendScript program to the server
+ * 
+ * TypeScript knows that the return type matches the program's return type.
+ * In this case, square(add(1, 2)) returns a number, so T is number.
+ */
 async function send<T>(program: T): Promise<T> {
   return (await fetch('/api', {
     method: 'POST',
@@ -364,20 +428,41 @@ async function send<T>(program: T): Promise<T> {
   })).json()
 }
 
-send(square(add(1, 2)))
+// TypeScript provides full autocomplete for math.add and math.square
+// It knows they take numbers and return numbers
+const result = await send(math.square(math.add(1, 2)))
+console.log(result) // 9
+
 ```
 
-We'll also generate the docs for this module.
+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
-npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
+npx typedoc --plugin typedoc-plugin-markdown --out ./docs ./example/typescript/math.ts
+```
+```
+[info] Loaded plugin typedoc-plugin-markdown
+[info] markdown generated at ./docs
 ```
 
-You can see the docs [here](./example/typescript/docs/globals.md)
+This generates markdown docs that can be shared with API consumers. See the
+[generated docs](./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.
+> [!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
 
@@ -529,36 +614,21 @@ code to create the AST.
 
 ### Callbacks
 
-Although it is possible to mix client and server functions, it works very
-different to ordinary functions. Client functions can be used but should be seen
-as a templating tool to make sendscript programs; just like one would use
-JavaScript with react templates. `items.map(deleteItem)` would return an array
-of sendscript function calls which can be given to sendscript's parse.
-
-Client functions cannot be called by sendscript functions (as of yet) since we
-cannot serialize client functions. No work has been done to have the server send
-back intermediate values to perform client function calls or by performing
-smaller sendscript program payloads that are passed to the client. Very
-interesting stuff to look into. You can achieve this now but it looks less clean
-because you have to do `send` calls which is a bit manual.
+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
-await send(updateUser(id, merge(await send(getUser(id)), { ...newValues })))
-```
-
-It might be interesting to allow configuration to create references that will
-trigger a send whenever await is called. That would remove the ability to create
-a single payload whenever using await. You can then write the above in the
-following manner.
+const api = references(['map', 'add'])
 
-```js
-await updateUser(id, merge(await getUser(id), { ...newValues }))
+const result = api.map((value) => api.add(value, 1))([1, 2, 3])
 ```
 
-Possible footgun is that updateUser is only performed when awaited (.then is
-called). This lazy behavior can trip users. This footgun could be resolved by
-checking if any outstanding work exists at the end of a step or the beginning of
-a new step.
+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
 
@@ -579,10 +649,10 @@ npm t -- report text-summary
 ```
 
 =============================== Coverage summary ===============================
-Statements   : 100% ( 512/512 )
-Branches     : 100% ( 147/147 )
+Statements   : 100% ( 516/516 )
+Branches     : 100% ( 157/157 )
 Functions    : 100% ( 23/23 )
-Lines        : 100% ( 512/512 )
+Lines        : 100% ( 516/516 )
 ================================================================================
 ```
 

package/README.mz

@@ -261,62 +261,103 @@ 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.
+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.
 
-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 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
-const userId = 'user-123'
-const program = {
-  unread: await fetchUnreadMessages(userId),
-  emptyTrash: await emptyTrash(userId),
-  archived: await archiveMessages(selectMessages({ old: true })),
-}
+import Stringify from 'sendscript/stringify.mjs'
+import references from 'sendscript/references.mjs'
 
-const result = await send(program)
+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)
 ```
 
-This operation is done in a single round-trip. The result is an object with the
-defined properties and returned values.
+The callback receives the generated SendScript program, and you decide how it is
+transported or executed.
 
 ## TypeScript
 
-There is a good use-case to write a module in 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.
 
-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.
+### Server-Side Module
 
-Let's say we have this module which we use on the server.
+Define your API as a TypeScript module on the server:
 
 ```bash|ts bash
 cat ./example/typescript/math.ts
 ```
 
-We can then coerce the types of the instrumented stubs.
+### 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
 ```
 
-We'll also generate the docs for this module.
+TypeScript knows the exact parameter types and return types for every function
+call.
+
+### Generating API Documentation
 
-```bash bash 1>&2
-npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
+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
 ```
 
-You can see the docs [here](./example/typescript/docs/globals.md)
+This generates markdown docs that can be shared with API consumers. See the
+[generated docs](./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.
+> [!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
 
@@ -468,36 +509,21 @@ code to create the AST.
 
 ### Callbacks
 
-Although it is possible to mix client and server functions, it works very
-different to ordinary functions. Client functions can be used but should be seen
-as a templating tool to make sendscript programs; just like one would use
-JavaScript with react templates. `items.map(deleteItem)` would return an array
-of sendscript function calls which can be given to sendscript's parse.
-
-Client functions cannot be called by sendscript functions (as of yet) since we
-cannot serialize client functions. No work has been done to have the server send
-back intermediate values to perform client function calls or by performing
-smaller sendscript program payloads that are passed to the client. Very
-interesting stuff to look into. You can achieve this now but it looks less clean
-because you have to do `send` calls which is a bit manual.
+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
-await send(updateUser(id, merge(await send(getUser(id)), { ...newValues })))
-```
+const api = references(['map', 'add'])
 
-It might be interesting to allow configuration to create references that will
-trigger a send whenever await is called. That would remove the ability to create
-a single payload whenever using await. You can then write the above in the
-following manner.
-
-```js
-await updateUser(id, merge(await getUser(id), { ...newValues }))
+const result = api.map((value) => api.add(value, 1))([1, 2, 3])
 ```
 
-Possible footgun is that updateUser is only performed when awaited (.then is
-called). This lazy behavior can trip users. This footgun could be resolved by
-checking if any outstanding work exists at the end of a step or the beginning of
-a new step.
+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
 

package/example/typescript/client.ts

@@ -1,9 +1,18 @@
-import math  from './math.client.ts'
+/**
+ * Client-side usage with type-safe SendScript
+ */
+
+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.
+/**
+ * Send a SendScript program to the server
+ * 
+ * TypeScript knows that the return type matches the program's return type.
+ * In this case, square(add(1, 2)) returns a number, so T is number.
+ */
 async function send<T>(program: T): Promise<T> {
   return (await fetch('/api', {
     method: 'POST',
@@ -11,4 +20,8 @@ async function send<T>(program: T): Promise<T> {
   })).json()
 }
 
-send(square(add(1, 2)))
+// TypeScript provides full autocomplete for math.add and math.square
+// It knows they take numbers and return numbers
+const result = await send(math.square(math.add(1, 2)))
+console.log(result) // 9
+

package/example/typescript/math.client.ts

@@ -1,5 +1,14 @@
+/**
+ * Client-side type-safe stubs for the math API
+ * 
+ * This file creates typed references that mirror the server's functions.
+ * The 'as typeof mathTypes' cast gives us full TypeScript support and IDE autocomplete.
+ */
+
 import type * as mathTypes from './math.ts'
-import Stringify from 'sendscript/stringify.mjs'
 import references from 'sendscript/references.mjs'
 
+// Create type-safe stubs - this tells TypeScript that 'add' and 'square' 
+// have the same signatures as the server functions
 export default references(['add', 'square']) as typeof mathTypes
+

package/example/typescript/math.ts

@@ -1,2 +1,9 @@
-export const add = (a: number, b: number) => a + b
-export const square = (a: number) => a * a
+/**
+ * Server-side math module with typed functions
+ * These functions will be called from the client through SendScript
+ */
+
+export const add = (a: number, b: number): number => a + b
+
+export const square = (a: number): number => a * a
+

package/package.json

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

package/references.mjs

@@ -7,7 +7,7 @@ import { awaitSymbol, call, ref, then, referenceSymbol } from './symbol.mjs'
  * @param {Array<string>} path - Path representing the function location in schema.
  * @returns {Function} Reference function with attached control methods (.then, .catch, toJSON).
  */
-function instrument (path) {
+function instrument (path, onAwait = null) {
   /**
    * Creates a callable reference invocation.
    *
@@ -15,7 +15,7 @@ function instrument (path) {
    * @returns {Function} New instrumented reference node.
    */
   function reference (...args) {
-    const called = instrument(path)
+    const called = instrument(path, onAwait)
 
     called.toJSON = () => ({
       [call]: call,
@@ -71,7 +71,7 @@ function instrument (path) {
       return dotThen(resolve, reject)
     }
 
-    const awaited = instrument(path)
+    const awaited = instrument(path, onAwait)
     delete awaited.then
 
     awaited.toJSON = () => ({
@@ -79,6 +79,10 @@ function instrument (path) {
       ref: reference
     })
 
+    if (typeof onAwait === 'function') {
+      return resolve(onAwait(awaited))
+    }
+
     return resolve(awaited)
   }
 
@@ -106,15 +110,15 @@ function instrument (path) {
  * @throws {Error} If schema format is invalid
  * @public
  */
-export default function References (schema, parentPath = []) {
+export default function References (schema, onAwait = null, parentPath = []) {
   return schema.reduce((acc, item) => {
     if (typeof item === 'string') {
-      acc[item] = instrument([...parentPath, item])
+      acc[item] = instrument([...parentPath, item], onAwait)
     } else if (Array.isArray(item)) {
       const [name, children] = item
 
       if (Array.isArray(children)) {
-        acc[name] = References(children, [...parentPath, name])
+        acc[name] = References(children, onAwait, [...parentPath, name])
       } else {
         throw new Error(`Expected children array for namespace "${name}"`)
       }

package/references.test.mjs

@@ -1,8 +1,62 @@
 import { test } from 'tap'
 import references from './references.mjs'
+import Stringify from './stringify.mjs'
 
 test('invalid uses of references', t => {
   t.throws(() => references([['a']]))
   t.throws(() => references([{}]))
   t.end()
 })
+
+test('native await hook is optional and backwards compatible', async t => {
+  const schema = ['add', 'square', 'identity', ['nested', ['value']]]
+  const stringify = Stringify()
+
+  const defaultApi = references(schema)
+  const defaultProgram = defaultApi.add(1, 2)
+
+  t.doesNotThrow(() => stringify(defaultProgram))
+  t.same(JSON.parse(stringify(defaultProgram))[0], 'call')
+
+  const calls = []
+  const api = references(schema, (program) => {
+    calls.push(program)
+    return 42
+  })
+
+  t.equal(await api.add(1, 2), 42)
+  t.equal(calls.length, 1)
+  t.equal(typeof calls[0], 'function')
+
+  const asyncApi = references(schema, async () => {
+    return await Promise.resolve(17)
+  })
+
+  t.equal(await asyncApi.identity(9), 17)
+
+  const rejectedApi = references(schema, async () => {
+    throw new Error('boom')
+  })
+
+  await t.rejects((async () => {
+    await rejectedApi.identity(9)
+  })(), { message: 'boom' })
+
+  const thenApi = references(schema)
+  const thenProgram = thenApi.add(1, 2).then(thenApi.square)
+  t.same(JSON.parse(stringify(thenProgram))[0], 'then')
+
+  const nestedApi = references([['outer', ['inner']]], (program) => program)
+  t.equal(typeof nestedApi.outer.inner, 'function')
+  t.same(JSON.parse(stringify(nestedApi.outer.inner(1)))[0], 'call')
+
+  const onAwaitApi = references(['add'], (program) => {
+    const serialized = stringify(program)
+    t.same(JSON.parse(serialized), ['await', ['call', ['ref', 'add'], [['leaf', '1'], ['leaf', '2']]]])
+    return 99
+  })
+
+  t.equal(await onAwaitApi.add(1, 2), 99)
+
+  t.end()
+})