sendscript 2.3.1 → 2.3.3

package/README.mz

@@ -11,23 +11,25 @@ Write JS code that you can run on servers, browsers or other clients.
 
 ## Introduction
 
-There has been interest in improving APIs by allowing aggregations in a
-single request. Examples include
+There has been interest in improving APIs by allowing aggregations in a single
+request. Examples include
 
-- [JSON-RPC](https://json-rpc.dev/) which allows you to do multiple requests
-  but it does not allow you to compose the return value of one endpoint to be the
+- [JSON-RPC](https://json-rpc.dev/) which allows you to do multiple requests but
+  it does not allow you to compose the return value of one endpoint to be the
   input/arguments of another.
 
-- [GraphQL](https://graphql.org/) is very cool but also introduces a new languages and the
-  tooling that is required to wield it.
+- [GraphQL](https://graphql.org/) is very cool but also introduces a new
+  languages and the tooling that is required to wield it.
 
-What SendScript attempts is to allow for very expressive queries and mutations to be performed
-that read and write like ordinary JS. That means that the queries and complete programs
-that are sent to the server from a client can also just run on the server as is. The only
-limitation being the serialization which by default is limited by JSON and could be extended by
-using more advanced (de)serialization libraries.
+What SendScript attempts is to allow for very expressive queries and mutations
+to be performed that read and write like ordinary JS. That means that the
+queries and complete programs that are sent to the server from a client can also
+just run on the server as is. The only limitation being the serialization which
+by default is limited by JSON and could be extended by using more advanced
+(de)serialization libraries.
 
-SendScript produces an intermediate JSON representation of the program. Let's see what that looks like.
+SendScript produces an intermediate JSON representation of the program. Let's
+see what that looks like.
 
 ```js|json node --input-type=module | tee /tmp/sendscript.json
 import Stringify from 'sendscript/stringify.mjs'
@@ -60,22 +62,26 @@ console.log(parse(program))
 SendScript does more than a simple function call. It supports function
 composition and even await.
 
-This package is nothing more than the absolute core of sendscript. It
-includes:
+This package is nothing more than the absolute core of sendscript. It includes:
 
 - The `references` function to create stubs to write the programs.
 - `stringify` which takes the program and returns a JSON string.
-- `parse` which takes the `stringify` JSON string and a real module and returns the result.
+- `parse` which takes the `stringify` JSON string and a real module and returns
+  the result.
 
-The naming could use more love and there are many things to solve either in the 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.
+The naming could use more love and there are many things to solve either in the
+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.
+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
 
@@ -89,7 +95,7 @@ We write a simple module.
 // ./example/math.mjs
 
 export const add = (a, b) => a + b
-export const square = a => a * a
+export const square = (a) => a * a
 ```
 
 ### Server
@@ -141,12 +147,10 @@ const stringify = Stringify()
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
 
-const send = program => {
+const send = (program) => {
   return new Promise((resolve, reject) => {
     client.emit('message', stringify(program), (error, result) => {
-      error
-        ? reject(error)
-        : resolve(result)
+      error ? reject(error) : resolve(result)
     })
   })
 }
@@ -179,9 +183,11 @@ pkill sendscript
 
 ## Repl
 
-Sendscript ships with a barebones (no-dependencies) node-repl script. One can run it by simply typing `sendscript` in their console.
+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.
+> Use the `DEBUG='*'` to enable all logs or `DEBUG='sendscript:*'` for
+> printingonly sendscript logs.
 
 ## Promises
 
@@ -193,27 +199,33 @@ Supported since vs `v2.3`.
 const getOrCreatePost = send(createPost(title).catch(createPost(title)))
 ```
 
-You will likely need to define better helpers that makes it safer to handle rejections and work with promises. It is however sensible to have
-this basic behavior for the sendscript DSL and parser.
+You will likely need to define better helpers that makes it safer to handle
+rejections and work with promises. It is however sensible to have this basic
+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.
+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.
+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 }))
+  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.
+This operation is done in a single round-trip. The result is an object with the
+defined properties and returned values.
 
 ## TypeScript
 
@@ -246,15 +258,16 @@ npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./e
 
 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.
-
+> [!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.
 
 ## Schema and Nested Modules
 
-Sendscript allows you to define your API as a **nested object of functions**, making it easy to organize your DSL into modules and submodules. Each function is instrumented so that when serialized, it produces a structured reference that can be safely sent and executed elsewhere.
+Sendscript allows you to define your API as a **nested object of functions**,
+making it easy to organize your DSL into modules and submodules. Each function
+is instrumented so that when serialized, it produces a structured reference that
+can be safely sent and executed elsewhere.
 
 ### Defining a Nested Module
 
@@ -286,17 +299,13 @@ Functions are referenced via their **path in the module tree**:
 ```js
 const { math, vector } = references(schema)
 
-math.add(
-  1,
-  vector.length(
-    vector.multiply([1,2], 3)
-  )
-)
+math.add(1, vector.length(vector.multiply([1, 2], 3)))
 ```
 
 ## Validation (using Zod)
 
-SendScript focuses on program serialization and execution. For runtime input validation, you can use [Zod](https://zod.dev).
+SendScript focuses on program serialization and execution. For runtime input
+validation, you can use [Zod](https://zod.dev).
 
 ### Validating structured input
 
@@ -304,7 +313,7 @@ SendScript focuses on program serialization and execution. For runtime input val
 const userSchema = z.object({
   id: z.string().uuid(),
   name: z.string(),
-  roles: z.array(z.string())
+  roles: z.array(z.string()),
 })
 
 export function createUser(user) {
@@ -322,13 +331,19 @@ export function createUser(user) {
 
 ## Leaf Serializer
 
-By default, SendScript uses JSON for serialization, which limits support to primitives and plain objects/arrays. To support richer JavaScript types like `Date`, `RegExp`, `BigInt`, `Map`, `Set`, and `undefined`, you can provide custom serialization functions.
+By default, SendScript uses JSON for serialization, which limits support to
+primitives and plain objects/arrays. To support richer JavaScript types like
+`Date`, `RegExp`, `BigInt`, `Map`, `Set`, and `undefined`, you can provide
+custom serialization functions.
 
-The `stringify` function accepts an optional `leafSerializer` parameter, and `parse` accepts an optional `leafDeserializer` parameter. These functions control how non-SendScript values (leaves) are encoded and decoded.
+The `stringify` function accepts an optional `leafSerializer` parameter, and
+`parse` accepts an optional `leafDeserializer` parameter. These functions
+control how non-SendScript values (leaves) are encoded and decoded.
 
 ### Example with superjson
 
-Here's how to use [superjson](https://github.com/blitz-js/superjson) to support extended types:
+Here's how to use [superjson](https://github.com/blitz-js/superjson) to support
+extended types:
 
 ```js
 import SuperJSON from 'superjson'
@@ -358,7 +373,10 @@ const program = {
   pattern: /foo/gi,
   count: BigInt('9007199254740992'),
   items: new Set([1, 2, 3]),
-  mapping: new Map([['a', 1], ['b', 2]])
+  mapping: new Map([
+    ['a', 1],
+    ['b', 2],
+  ]),
 }
 
 // Serialize with custom leaf serializer
@@ -368,8 +386,8 @@ const json = stringify(processData(program))
 const env = {
   processData: (data) => ({
     success: true,
-    received: data
-  })
+    received: data,
+  }),
 }
 
 // Parse with custom leaf deserializer
@@ -378,24 +396,8 @@ const parse = Parse(schema, env, leadDeserializer)
 const result = parse(json)
 ```
 
-The leaf wrapper format is `['leaf', serializedPayload]`, making it unambiguous and safe from colliding with SendScript operators.
-
-## 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
-```
+The leaf wrapper format is `['leaf', serializedPayload]`, making it unambiguous
+and safe from colliding with SendScript operators.
 
 ## Changelog
 
@@ -406,24 +408,17 @@ The [changelog][changelog] is generated using the useful
 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
+## Issues
 
-- [ ] Support for simple lambdas to compose functions more easily.
+See [issues][issues] for roadmap and known bugs.
 
-[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
+[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
+[issues]: https://github.com/bas080/sendscript/issues

package/example/client.socket.io.mjs

@@ -11,12 +11,10 @@ const stringify = Stringify()
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
 
-const send = program => {
+const send = (program) => {
   return new Promise((resolve, reject) => {
     client.emit('message', stringify(program), (error, result) => {
-      error
-        ? reject(error)
-        : resolve(result)
+      error ? reject(error) : resolve(result)
     })
   })
 }

package/example/math.mjs

@@ -1,4 +1,4 @@
 // ./example/math.mjs
 
 export const add = (a, b) => a + b
-export const square = a => a * a
+export const square = (a) => a * a

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/69e8cc48251af650c02faf3214ff0f9c2b61dbc9/example/typescript/math.ts#L1)
+Defined in: [math.ts:1](https://github.com/bas080/sendscript/blob/08eb266b06d8998e6849dbc5c9738fbe782ada18/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/69e8cc48251af650c02faf3214ff0f9c2b61dbc9/example/typescript/math.ts#L2)
+Defined in: [math.ts:2](https://github.com/bas080/sendscript/blob/08eb266b06d8998e6849dbc5c9738fbe782ada18/example/typescript/math.ts#L2)
 
 ## Parameters
 

package/package.json

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

package/parse.mjs

@@ -6,13 +6,14 @@ function flattenSchema (schema) {
 
   for (const item of schema) {
     if (typeof item === 'string') {
-      // leaf function
       obj[item] = true
     } else if (Array.isArray(item)) {
       const [name, children] = item
+
       if (!Array.isArray(children)) {
         throw new Error(`Expected children array for namespace "${name}"`)
       }
+
       obj[name] = flattenSchema(children)
     } else {
       throw new Error('Schema items must be strings or [name, children] arrays')
@@ -38,7 +39,6 @@ const spy = (type, fn) => (...args) => {
   return value
 }
 
-// Recursively resolve awaited values in a parsed tree
 const evaluate = spy('eval', (value, awaits = []) => {
   if (value === undefinedSentinel) return undefined
 
@@ -47,49 +47,41 @@ const evaluate = spy('eval', (value, awaits = []) => {
 
     if (operator === 'await') {
       const [index] = rest
-      // No need to check index. It is closely tied to the program.
-      // if (typeof index !== 'number' || index < 0 || index >= awaitsResolved.length) {
-      //   throw new Error(`Invalid await index: ${index}`);
-      // }
       return awaits[index]
     }
 
     if (operator === 'then') {
       const [v, onResolve, onReject] = rest
-      return evaluate(v, awaits).then(evaluate(onResolve, awaits), evaluate(onReject, awaits))
+      return evaluate(v, awaits).then(
+        evaluate(onResolve, awaits),
+        evaluate(onReject, awaits)
+      )
     }
 
     if (operator === 'call') {
-      // Step 1: evaluate the function itself
       let [fn, args] = rest
       fn = evaluate(fn, awaits)
 
-      // Step 2: evaluate each argument AFTER fn is ready
       for (let i = 0; i < args.length; i++) {
         args[i] = evaluate(args[i], awaits)
       }
 
-      // Step 3: call the function
       return fn(...args)
     }
 
     if (operator === 'quote') {
       const [quoted] = rest
-      return quoted // return as-is without evaluating
+      return quoted
     }
 
-    // fallback: evaluate each element
-    // re-uses the array again.
-
-    for (let index = 0; index < value.length; index++) {
-      const item = value[index]
-      value[index] = evaluate(item, awaits)
+    for (let i = 0; i < value.length; i++) {
+      value[i] = evaluate(value[i], awaits)
     }
+
     return value
   }
 
   if (isPlainObject(value)) {
-    // We muatate the object itself. No need to make a new one.
     for (const key of Object.keys(value)) {
       value[key] = evaluate(value[key], awaits)
     }
@@ -99,23 +91,56 @@ const evaluate = spy('eval', (value, awaits = []) => {
   return value
 })
 
+/**
+ * Default deserializer for leaf nodes.
+ *
+ * @param {string} text
+ * @returns {any}
+ * @public
+ */
 const defaultLeafDeserializer = (text) => JSON.parse(text)
 
-export default (schemaArg, env, deserialize = defaultLeafDeserializer) => {
+/**
+ * Creates a program parser for a given schema and environment.
+ *
+ * The parser:
+ * - resolves references into runtime functions
+ * - deserializes leaf nodes
+ * - collects and executes async awaits
+ * - evaluates AST-like JSON programs
+ *
+ * @param {Array<string | [string, Array]>} schemaArg
+ * @param {Object} env - runtime environment for refs
+ * @param {(text: string) => any} [deserialize=defaultLeafDeserializer]
+ * @returns {(program: string) => any|Promise<any>}
+ * @public
+ */
+export default function Parse (schemaArg, env, deserialize = defaultLeafDeserializer) {
   const schema = flattenSchema(schemaArg)
 
+  /**
+   * Parses and executes a serialized program.
+   *
+   * @param {string} program - JSON encoded program
+   * @returns {any|Promise<any>}
+   * @public
+   */
   return function parse (program) {
     debug('program', program)
     const awaits = []
 
-    // Creates the list of awaits that will resolve in order
-    // and also deserializes the leaves.
+    /**
+     * JSON reviver used during parsing.
+     * Converts encoded operators into runtime structures.
+     *
+     * @param {string} key
+     * @param {any} value
+     * @returns {any}
+     */
     const reviver = spy('revive', (key, value) => {
       if (value === null) return value
 
-      if (!Array.isArray(value)) {
-        return value
-      }
+      if (!Array.isArray(value)) return value
 
       const [operator, ...rest] = value
 
@@ -126,7 +151,6 @@ export default (schemaArg, env, deserialize = defaultLeafDeserializer) => {
 
       if (operator === 'await') {
         const [program] = rest
-
         return ['await', awaits.push(program) - 1]
       }
 
@@ -151,19 +175,17 @@ export default (schemaArg, env, deserialize = defaultLeafDeserializer) => {
     })
 
     const parsed = JSON.parse(program, reviver)
-
     debug('parsed', parsed)
 
     if (awaits.length) {
       debug('awaits', awaits)
 
       return (async function () {
-        for (let index = 0; index < awaits.length; index++) {
-          awaits[index] = await evaluate(awaits[index], awaits)
+        for (let i = 0; i < awaits.length; i++) {
+          awaits[i] = await evaluate(awaits[i], awaits)
         }
 
         debug('awaits(awaited)', awaits)
-
         return evaluate(parsed, awaits)
       })()
     }

package/references.mjs

@@ -1,6 +1,19 @@
 import { awaitSymbol, call, ref, then, referenceSymbol } from './symbol.mjs'
 
+/**
+ * Creates a callable reference node bound to a path.
+ * Used to build a lazy/instrumented execution structure.
+ *
+ * @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) {
+  /**
+   * Creates a callable reference invocation.
+   *
+   * @param {...any} args - Arguments passed to the call.
+   * @returns {Function} New instrumented reference node.
+   */
   function reference (...args) {
     const called = instrument(path)
 
@@ -13,6 +26,13 @@ function instrument (path) {
     return called
   }
 
+  /**
+   * Internal helper for building promise-like continuation nodes.
+   *
+   * @param {Function|null} resolve
+   * @param {Function|null} reject
+   * @returns {Function} Instrumented continuation node.
+   */
   function dotThen (resolve, reject) {
     const node = instrument(path)
 
@@ -26,18 +46,32 @@ function instrument (path) {
     return node
   }
 
+  /**
+   * Registers rejection handler (promise-style).
+   *
+   * @param {Function} reject
+   * @returns {Function}
+   */
   reference.catch = (reject) => {
     return dotThen(null, reject)
   }
 
+  /**
+   * Handles async chaining or awaiting logic.
+   *
+   * If resolve/reject contain a reference marker, it behaves like a .then chain.
+   * Otherwise it behaves like an await wrapper.
+   *
+   * @param {Function} resolve
+   * @param {Function} reject
+   * @returns {Function|any}
+   */
   reference.then = (resolve, reject) => {
-    // That is how we know if it is an await or a .then call.
     if (resolve?.[referenceSymbol] || reject?.[referenceSymbol]) {
       return dotThen(resolve, reject)
     }
 
     const awaited = instrument(path)
-    // Prevent infinite recur
     delete awaited.then
 
     awaited.toJSON = () => ({
@@ -48,6 +82,11 @@ function instrument (path) {
     return resolve(awaited)
   }
 
+  /**
+   * JSON representation of the reference path node.
+   *
+   * @returns {{ref: symbol, path: Array<string>}}
+   */
   reference.toJSON = () => ({
     [ref]: ref,
     path
@@ -58,17 +97,29 @@ function instrument (path) {
   return reference
 }
 
-export default function module (schema, parentPath = []) {
+/**
+ * Builds a nested API structure from a schema definition.
+ *
+ * Schema supports:
+ * - string => leaf function node
+ * - [name, children] => namespace with nested schema
+ *
+ * @param {Array<string | [string, Array]>} schema
+ * @param {Array<string>} [parentPath=[]]
+ * @returns {Object} Nested instrumented API object
+ *
+ * @throws {Error} If schema format is invalid
+ * @public
+ */
+export default function References (schema, parentPath = []) {
   return schema.reduce((acc, item) => {
     if (typeof item === 'string') {
-      // leaf function
       acc[item] = instrument([...parentPath, item])
     } else if (Array.isArray(item)) {
       const [name, children] = item
 
       if (Array.isArray(children)) {
-        // recurse: children can be strings or [name, children] arrays
-        acc[name] = module(children, [...parentPath, name])
+        acc[name] = References(children, [...parentPath, name])
       } else {
         throw new Error(`Expected children array for namespace "${name}"`)
       }