sendscript 1.0.5 → 1.0.6

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).
 
+#### [v1.0.6](https://github.com/bas080/sendscript/compare/v1.0.5...v1.0.6)
+
+- Update tap to 21.6.3 [`c1769d9`](https://github.com/bas080/sendscript/commit/c1769d9a24148e63d27b0e5a7456213bec64763e)
+- Add introduction to readme [`a21a494`](https://github.com/bas080/sendscript/commit/a21a494616d5ad8c99f9a2904ef529ea85104a99)
+
 #### [v1.0.5](https://github.com/bas080/sendscript/compare/v1.0.4...v1.0.5)
 
+> 5 April 2026
+
 - Add publish to npm workflow [`aaaa97d`](https://github.com/bas080/sendscript/commit/aaaa97d1024d6b5ed574a2cd103035949ec8280d)
 
 #### [v1.0.4](https://github.com/bas080/sendscript/compare/v1.0.3...v1.0.4)

package/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+
+For the README.mz examples to work we need sendscript to be linked.
+
+```bash bash > /dev/null
+set -e
+
+npm link
+npm link sendscript
+cd ./example
+npm ci
+npm link sendscript
+```
+
+Generate the README from the mz file.
+
+```bash bash
+markatzea ./README.mz | tee ./README.md
+
+npx markdown-toc -i README.md
+
+git add *.md ./example
+```

package/README.md

@@ -9,6 +9,7 @@ Write JS code that you can run on servers, browsers or other clients.
 
 <!-- toc -->
 
+- [Introduction](#introduction)
 - [Socket example](#socket-example)
   * [Module](#module)
   * [Server](#server)
@@ -25,6 +26,75 @@ Write JS code that you can run on servers, browsers or other clients.
 
 <!-- tocstop -->
 
+## Introduction
+
+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
+  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.
+
+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.
+
+```js
+import stringify from 'sendscript/stringify.mjs'
+import module from 'sendscript/module.mjs'
+
+const { add } = module(['add'])
+
+console.log(stringify(add(1,2)))
+```
+```json
+["call",["ref","add"],[1,2]]
+```
+
+We can then parse that JSON and it will evaluate down to a value.
+
+```js
+import Parse from 'sendscript/parse.mjs'
+
+const module = {
+  add(a, b) {
+    return a + b
+  }
+}
+
+const parse = Parse(module)
+
+const program = '["call",["ref","add"],[1,2]]'
+
+console.log(parse(program))
+```
+```json
+3
+```
+
+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:
+
+- The `module` 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.
+
+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.
@@ -33,17 +103,6 @@ needs.
 
 For this example we'll use [socket.io][socket.io].
 
-```bash
-set -e
-
-npm link
-cd ./example
-npm ci
-npm link sendscript
-```
-
-> We use the `--no-save` option because it's only for demonstration purposes.
-
 ### Module
 
 We write a simple module.
@@ -234,7 +293,7 @@ npm install --no-save \
   typedoc \
   typedoc-plugin-markdown
 
-typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
+npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
 ```
 
 You can see the docs [here](./example/typescript/docs/globals.md)
@@ -254,11 +313,11 @@ npm t -- report text-summary
 ```
 ```
 
-> sendscript@1.0.5 test
+> sendscript@1.0.6 test
 > tap -R silent
 
 
-> sendscript@1.0.5 test
+> sendscript@1.0.6 test
 > tap report text-summary
 
 

package/README.mz

@@ -9,6 +9,69 @@ Write JS code that you can run on servers, browsers or other clients.
 
 <!-- toc -->
 
+## Introduction
+
+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
+  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.
+
+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.
+
+```js|json node --input-type=module | tee /tmp/sendscript.json
+import stringify from 'sendscript/stringify.mjs'
+import module from 'sendscript/module.mjs'
+
+const { add } = module(['add'])
+
+console.log(stringify(add(1,2)))
+```
+
+We can then parse that JSON and it will evaluate down to a value.
+
+```js|json node --input-type=module
+import Parse from 'sendscript/parse.mjs'
+
+const module = {
+  add(a, b) {
+    return a + b
+  }
+}
+
+const parse = Parse(module)
+
+const program = '["call",["ref","add"],[1,2]]'
+
+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:
+
+- The `module` 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.
+
+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.
@@ -17,17 +80,6 @@ needs.
 
 For this example we'll use [socket.io][socket.io].
 
-```bash bash > /dev/null
-set -e
-
-npm link
-cd ./example
-npm ci
-npm link sendscript
-```
-
-> We use the `--no-save` option because it's only for demonstration purposes.
-
 ### Module
 
 We write a simple module.
@@ -184,7 +236,7 @@ npm install --no-save \
   typedoc \
   typedoc-plugin-markdown
 
-typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
+npx typedoc --plugin typedoc-plugin-markdown --out ./example/typescript/docs ./example/typescript/math.ts
 ```
 
 You can see the docs [here](./example/typescript/docs/globals.md)

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sendscript",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Blur the line between server and client code.",
   "module": true,
   "main": "index.mjs",
@@ -17,13 +17,13 @@
   },
   "scripts": {
     "test": "tap",
-    "version": "npm run docs && git add *.md example",
-    "docs": "markatzea README.mz | tee README.md && npx markdown-toc -i README.md"
+    "version": "npm run docs",
+    "docs": "markatzea CONTRIBUTING.md"
   },
   "author": "Bas Huis",
   "license": "MIT",
   "devDependencies": {
-    "tap": "^21.6.2"
+    "tap": "^21.6.3"
   },
   "dependencies": {
     "debug": "^4.4.3"