sendscript 2.3.8 → 2.4.0

package/CHANGELOG.md

@@ -4,8 +4,22 @@ 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.4.0](https://github.com/bas080/sendscript/compare/v2.3.9...v2.4.0)
+
+- Update tap to 4.5.4 [`5249a85`](https://github.com/bas080/sendscript/commit/5249a85a08b10485f0d64058fd2c8bcaae84edda)
+- Add fn and args support [`6110654`](https://github.com/bas080/sendscript/commit/6110654fa039d17cd9ba0e15f749756b615b5d09)
+- Move transport agnostic section to socket example [`3a92257`](https://github.com/bas080/sendscript/commit/3a9225787df16a0fd83293bfa14d91b74a46d070)
+
+#### [v2.3.9](https://github.com/bas080/sendscript/compare/v2.3.8...v2.3.9)
+
+> 14 April 2026
+
+- Remove schema description from reference and schema shape [`7126829`](https://github.com/bas080/sendscript/commit/7126829b5968588d7c9377ee643b88465f3fe16e)
+
 #### [v2.3.8](https://github.com/bas080/sendscript/compare/v2.3.7...v2.3.8)
 
+> 14 April 2026
+
 - Move typedoc dep to dev deps [`a084b1d`](https://github.com/bas080/sendscript/commit/a084b1dad2f76ceb3b79fac390210f1ccfa368f8)
 
 #### [v2.3.7](https://github.com/bas080/sendscript/compare/v2.3.6...v2.3.7)

package/README.md

@@ -25,6 +25,7 @@ Write JS code that you can run on servers, browsers or other clients.
   * [Server](#server)
   * [Client](#client)
 - [Repl](#repl)
+- [Functions](#functions)
 - [Promises](#promises)
   * [.then / .catch](#then--catch)
   * [await](#await)
@@ -114,17 +115,14 @@ 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
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
 ### defaultLeafParse
 
+[parse.mjs:49-49](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/parse.mjs#L49-L49 "Source code on GitHub")
+
 Default deserializer for leaf nodes.
 
 #### Parameters
@@ -135,6 +133,8 @@ Returns **any**&#x20;
 
 ### Parse
 
+[parse.mjs:68-215](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/parse.mjs#L68-L215 "Source code on GitHub")
+
 #### Parameters
 
 *   `schema` **[Schema](#schema)**&#x20;
@@ -145,6 +145,8 @@ Returns **[parse](#parse)**&#x20;
 
 ### parse
 
+[parse.mjs:78-214](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/parse.mjs#L78-L214 "Source code on GitHub")
+
 Parses and executes a serialized program.
 
 #### Parameters
@@ -155,17 +157,14 @@ Returns **(any | [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Ref
 
 ### References
 
-Builds a nested API structure from a schema definition.
-
-Schema supports:
+[references.mjs:109-127](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/references.mjs#L109-L127 "Source code on GitHub")
 
-*   string => leaf function node
-*   \[name, children] => namespace with nested schema
+Builds a nested API structure from a schema definition.
 
 #### Parameters
 
 *   `schema` **[Schema](#schema)**&#x20;
-*   `parentPath` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>**  (optional, default `[]`)
+*   `parentPath`   (optional, default `[]`)
 
 <!---->
 
@@ -175,12 +174,16 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### SchemaNode
 
+[schema.mjs:1-19](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/schema.mjs#L1-L6 "Source code on GitHub")
+
 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
 
+[schema.mjs:1-19](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/schema.mjs#L8-L18 "Source code on GitHub")
+
 A schema defines the structure of the runtime API tree.
 
 *   string → leaf node
@@ -192,6 +195,8 @@ Type: [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global
 
 ### defaultLeafStringify
 
+[stringify.mjs:37-47](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/stringify.mjs#L37-L47 "Source code on GitHub")
+
 Default strict serializer for leaf values.
 
 Rejects non-JSON-safe values.
@@ -204,6 +209,8 @@ Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### Stringify
 
+[stringify.mjs:56-157](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/stringify.mjs#L56-L157 "Source code on GitHub")
+
 Creates a stringify function for SendScript AST structures.
 
 #### Parameters
@@ -214,6 +221,8 @@ Returns **[stringify](#stringify)**&#x20;
 
 ### stringify
 
+[stringify.mjs:64-156](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/stringify.mjs#L64-L156 "Source code on GitHub")
+
 Serializes a program into a JSON string representation.
 
 #### Parameters
@@ -224,6 +233,9 @@ Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ## Socket example
 
+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.
+
 For this example we'll use [socket.io][socket.io].
 
 ### Module
@@ -330,6 +342,24 @@ run it by simply typing `sendscript` in their console.
 > Use the `DEBUG='*'` to enable all logs or `DEBUG='sendscript:*'` for
 > printingonly sendscript logs.
 
+## Functions
+
+SendScript as of `v2.4` supports functions to do basic templating. It does not
+support async functions and will throw an error when you define one.
+
+Under the hood the function is called when it is being parsed. Make sure you
+understand what you are doing when mixing client and server functions.
+
+```js
+map((a) => add(a, 1))([1, 2, 3]))
+```
+
+It also supports nested functions.
+
+```js
+map(call)(map((a) => () => add(a, 1))([1, 2, 3]))
+```
+
 ## Promises
 
 ### .then / .catch

package/README.mz

@@ -74,17 +74,15 @@ 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
 
 <!-- Reference -->
 
 ## Socket example
 
+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.
+
 For this example we'll use [socket.io][socket.io].
 
 ### Module
@@ -189,6 +187,24 @@ run it by simply typing `sendscript` in their console.
 > Use the `DEBUG='*'` to enable all logs or `DEBUG='sendscript:*'` for
 > printingonly sendscript logs.
 
+## Functions
+
+SendScript as of `v2.4` supports functions to do basic templating. It does not
+support async functions and will throw an error when you define one.
+
+Under the hood the function is called when it is being parsed. Make sure you
+understand what you are doing when mixing client and server functions.
+
+```js
+map((a) => add(a, 1))([1, 2, 3]))
+```
+
+It also supports nested functions.
+
+```js
+map(call)(map((a) => () => add(a, 1))([1, 2, 3]))
+```
+
 ## Promises
 
 ### .then / .catch

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

@@ -8,7 +8,7 @@
 
 > **add**(`a`, `b`): `number`
 
-Defined in: [math.ts:1](https://github.com/bas080/sendscript/blob/a084b1dad2f76ceb3b79fac390210f1ccfa368f8/example/typescript/math.ts#L1)
+Defined in: [math.ts:1](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/example/typescript/math.ts#L1)
 
 ## Parameters
 

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

@@ -8,7 +8,7 @@
 
 > **square**(`a`): `number`
 
-Defined in: [math.ts:2](https://github.com/bas080/sendscript/blob/a084b1dad2f76ceb3b79fac390210f1ccfa368f8/example/typescript/math.ts#L2)
+Defined in: [math.ts:2](https://github.com/bas080/sendscript/blob/5249a85a08b10485f0d64058fd2c8bcaae84edda/example/typescript/math.ts#L2)
 
 ## Parameters
 

package/index.test.mjs

@@ -34,6 +34,7 @@ const myModuleOrig = {
   hello: 'world',
   noop: () => {},
   resolve: (x) => Promise.resolve(x),
+  call: (fn, ...args) => fn(...args),
   reject: x => Promise.reject(x),
   asyncFn: async () => 'my-async-function',
   instanceOf: (x, t) => x instanceof t,
@@ -85,15 +86,59 @@ test('should evaluate basic expressions correctly', async (t) => {
     always,
     multiply3,
     sayHello,
+    call,
     nested
   } = api
 
+  t.test('throws when async fn is provided', async t => {
+    t.throws(() => run(identity(async () => {})))
+    t.end()
+  })
+
+  t.test('supports fns with arguments', async t => {
+    t.same(run(map((a) => add(a, 1))([1, 2, 3])), [2, 3, 4])
+    t.end()
+  })
+
+  t.test('nested fns with arguments', async t => {
+    t.same(run(
+      map(call)(
+        map((a) => () => add(a, 1))([1, 2, 3])
+      )), [2, 3, 4])
+    t.end()
+  })
+
+  t.test('supports fns without arguments', async t => {
+    t.equal(run(() => add(1, 2))(), 3)
+    t.equal(run(always(() => 42)()()), 42)
+    t.equal(run(always(x => add(x, 42))()(2)), 44)
+    t.end()
+  })
+
+  t.test('supports binding reference functions on client', async t => {
+    const plusOne = add.bind(null, 1)
+
+    t.equal(run(plusOne(1)), 2)
+    t.equal(await run(resolve(1).then(plusOne)), 2)
+
+    // Even this works.
+    t.equal(await run(resolve(1).then(v => plusOne(v))), 2)
+
+    t.end()
+  })
+
   t.test('supports .then', async t => {
+    const something = 30
+
     t.rejects(run(reject('error')))
 
     t.equal(await run(reject('error').catch(sayHello)), 'hello error')
     t.equal(await run(reject('error').then(null, sayHello)), 'hello error')
 
+    // .then with fns just works and I do not know why.
+    t.equal(await run(resolve(32).then(() => add(something, 1))), 31)
+    t.equal(await run(resolve(32).then(value => add(something, value))), 62)
+
     t.equal(await run(resolve('value').then(sayHello)), 'hello value')
     t.equal(await run(resolve('value').then(sayHello, noop)), 'hello value')
 

package/package.json

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

package/parse.mjs

@@ -39,58 +39,6 @@ const spy = (type, fn) => (...args) => {
   return value
 }
 
-const evaluate = spy('eval', (value, awaits = []) => {
-  if (value === undefinedSentinel) return undefined
-
-  if (Array.isArray(value)) {
-    const [operator, ...rest] = value
-
-    if (operator === 'await') {
-      const [index] = rest
-      return awaits[index]
-    }
-
-    if (operator === 'then') {
-      const [v, onResolve, onReject] = rest
-      return evaluate(v, awaits).then(
-        evaluate(onResolve, awaits),
-        evaluate(onReject, awaits)
-      )
-    }
-
-    if (operator === 'call') {
-      let [fn, args] = rest
-      fn = evaluate(fn, awaits)
-
-      for (let i = 0; i < args.length; i++) {
-        args[i] = evaluate(args[i], awaits)
-      }
-
-      return fn(...args)
-    }
-
-    if (operator === 'quote') {
-      const [quoted] = rest
-      return quoted
-    }
-
-    for (let i = 0; i < value.length; i++) {
-      value[i] = evaluate(value[i], awaits)
-    }
-
-    return value
-  }
-
-  if (isPlainObject(value)) {
-    for (const key of Object.keys(value)) {
-      value[key] = evaluate(value[key], awaits)
-    }
-    return value
-  }
-
-  return value
-})
-
 /**
  * Default deserializer for leaf nodes.
  *
@@ -131,6 +79,76 @@ export default function Parse (schema, env, leafParse = defaultLeafParse) {
     debug('program', program)
     const awaits = []
 
+    const evaluateOuter = spy('eval', (env, value) => {
+      const evaluate = evaluateOuter.bind(null, env)
+
+      if (value === undefinedSentinel) return undefined
+
+      if (Array.isArray(value)) {
+        const [operator, ...rest] = value
+
+        if (operator === 'await') {
+          const [index] = rest
+          return awaits[index]
+        }
+
+        if (operator === 'then') {
+          const [v, onResolve, onReject] = rest
+          return evaluate(v).then(
+            evaluate(onResolve),
+            evaluate(onReject)
+          )
+        }
+
+        if (operator === 'fn') {
+          const [argIds, body] = [...rest]
+
+          return (...args) => {
+            const newEnv = Object.create(env)
+
+            argIds.forEach((id, index) => {
+              newEnv[id] = args[index]
+            })
+
+            return evaluateOuter(newEnv, body)
+          }
+        }
+
+        if (operator === 'arg') {
+          const [id] = rest
+
+          return env[id]
+        }
+
+        if (operator === 'call') {
+          let [fn, args] = rest
+          fn = evaluate(fn)
+
+          return fn(...args.map(evaluate))
+        }
+
+        if (operator === 'quote') {
+          const [quoted] = rest
+          return quoted
+        }
+
+        for (let i = 0; i < value.length; i++) {
+          value[i] = evaluate(value[i])
+        }
+
+        return value
+      }
+
+      if (isPlainObject(value)) {
+        for (const key of Object.keys(value)) {
+          value[key] = evaluate(value[key])
+        }
+        return value
+      }
+
+      return value
+    })
+
     /**
      * JSON reviver used during parsing.
      * Converts encoded operators into runtime structures.
@@ -184,14 +202,14 @@ export default function Parse (schema, env, leafParse = defaultLeafParse) {
 
       return (async function () {
         for (let i = 0; i < awaits.length; i++) {
-          awaits[i] = await evaluate(awaits[i], awaits)
+          awaits[i] = await evaluateOuter({}, awaits[i])
         }
 
         debug('awaits(awaited)', awaits)
-        return evaluate(parsed, awaits)
+        return evaluateOuter({}, parsed)
       })()
     }
 
-    return evaluate(parsed)
+    return evaluateOuter({}, parsed)
   }
 }

package/references.mjs

@@ -100,12 +100,7 @@ function instrument (path) {
 /**
  * Builds a nested API structure from a schema definition.
  *
- * Schema supports:
- * - string => leaf function node
- * - [name, children] => namespace with nested schema
- *
  * @param {Schema} schema
- * @param {Array<string>} [parentPath=[]]
  * @returns {Object} Nested instrumented API object
  *
  * @throws {Error} If schema format is invalid

package/stringify.mjs

@@ -2,14 +2,20 @@ import Debug from './debug.mjs'
 import { SendScriptSerializationError } from './error.mjs'
 import {
   awaitSymbol,
+  referenceSymbol,
   then,
   call,
   ref
 } from './symbol.mjs'
 
+const asyncFunction = async function () {}
+asyncFunction()
+const AsyncFunction = (asyncFunction).constructor
+
 const debug = Debug.extend('stringify')
 
-const keywords = ['ref', 'call', 'quote', 'await', 'leaf']
+const keywords = ['ref', 'call', 'quote', 'await', 'leaf', 'arg', 'fn']
+const argSymbol = Symbol('arg')
 
 const isKeyword = (v) => keywords.includes(v)
 
@@ -19,67 +25,6 @@ const isPlainObject = (value) => {
   return proto === Object.prototype || proto === null
 }
 
-function transformValue (value, leafSerializer) {
-  debug(value)
-
-  if (value === null) return null
-
-  // unwrap function wrappers (instrumented nodes)
-  if (typeof value === 'function' && typeof value.toJSON === 'function') {
-    return transformValue(value.toJSON(), leafSerializer)
-  }
-
-  if (value && value[ref]) {
-    return ['ref', ...value.path]
-  }
-
-  if (value && value[call]) {
-    return [
-      'call',
-      transformValue(value.ref, leafSerializer),
-      transformValue(value.args, leafSerializer)
-    ]
-  }
-
-  if (value && value[awaitSymbol]) {
-    return ['await', transformValue(value.ref, leafSerializer)]
-  }
-
-  if (value && value[then]) {
-    return [
-      'then',
-      transformValue(value.ref, leafSerializer),
-      transformValue(value.resolve || null, leafSerializer),
-      transformValue(value.reject || null, leafSerializer)
-    ]
-  }
-
-  if (Array.isArray(value)) {
-    const [operator, ...rest] = value
-
-    if (isKeyword(operator)) {
-      return [
-        ['quote', operator],
-        ...rest.map((item) => transformValue(item, leafSerializer))
-      ]
-    }
-
-    return value.map((item) => transformValue(item, leafSerializer))
-  }
-
-  if (isPlainObject(value)) {
-    const result = {}
-
-    for (const key of Object.keys(value)) {
-      result[key] = transformValue(value[key], leafSerializer)
-    }
-
-    return result
-  }
-
-  return ['leaf', leafSerializer(value)]
-}
-
 /**
  * Default strict serializer for leaf values.
  *
@@ -117,6 +62,96 @@ export default function Stringify (leafStringify = defaultLeafStringify) {
    * @public
    */
   return function stringify (program) {
-    return JSON.stringify(transformValue(program, leafStringify))
+    // Reset the argId
+    let argId = 0
+
+    function transformValue (value) {
+      debug(value)
+
+      if (value === null) return null
+
+      // unwrap function wrappers (instrumented nodes)
+      if (value && value[referenceSymbol]) {
+        return transformValue(value.toJSON())
+      }
+
+      // Is a simple function. We call it to get the template.
+      if (typeof value === 'function') {
+        if (value instanceof AsyncFunction) {
+          throw new SendScriptSerializationError('Sendscript does not support async functions as of yet.')
+        }
+
+        const args = []
+        const argIds = []
+
+        for (let i = 0; i < value.length; i++) {
+          const arg = argId++
+          const placeholder = ['arg', arg]
+
+          placeholder[argSymbol] = argSymbol
+
+          args.push(placeholder)
+          argIds.push(arg)
+        }
+
+        return ['fn', argIds, transformValue(value(...args))]
+      }
+
+      if (value && value[argSymbol]) {
+        return value
+      }
+
+      if (value && value[ref]) {
+        return ['ref', ...value.path]
+      }
+
+      if (value && value[call]) {
+        return [
+          'call',
+          transformValue(value.ref),
+          transformValue(value.args)
+        ]
+      }
+
+      if (value && value[awaitSymbol]) {
+        return ['await', transformValue(value.ref)]
+      }
+
+      if (value && value[then]) {
+        return [
+          'then',
+          transformValue(value.ref),
+          transformValue(value.resolve || null),
+          transformValue(value.reject || null)
+        ]
+      }
+
+      if (Array.isArray(value)) {
+        const [operator, ...rest] = value
+
+        if (isKeyword(operator)) {
+          return [
+            ['quote', operator],
+            ...rest.map((item) => transformValue(item))
+          ]
+        }
+
+        return value.map((item) => transformValue(item))
+      }
+
+      if (isPlainObject(value)) {
+        const result = {}
+
+        for (const key of Object.keys(value)) {
+          result[key] = transformValue(value[key])
+        }
+
+        return result
+      }
+
+      return ['leaf', leafStringify(value)]
+    }
+
+    return JSON.stringify(transformValue(program))
   }
 }