sendscript 2.4.3 → 2.5.0

package/CHANGELOG.md

@@ -4,8 +4,15 @@ 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)

package/README.md

@@ -306,27 +306,40 @@ 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
 
@@ -601,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
 
@@ -651,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,27 +261,40 @@ 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
 
@@ -496,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 })))
-```
-
-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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sendscript",
-  "version": "2.4.3",
+  "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()
+})