sendscript 0.1.0 → 0.1.2

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).
 
+#### [v0.1.2](https://github.com/bas080/sendscript/compare/v0.1.1...v0.1.2)
+
+- Update tap to 10.9.5 [`4e3ddcc`](https://github.com/bas080/sendscript/commit/4e3ddcca823ca64c52bc1966ac23a712480d6c4d)
+
+#### [v0.1.1](https://github.com/bas080/sendscript/compare/v0.1.0...v0.1.1)
+
+> 4 January 2024
+
+- Add a json schema for the sendscript program [`2acf884`](https://github.com/bas080/sendscript/commit/2acf8848134e1ae175afc0af9c5f1e93c4039f8f)
+- Document a way of using sendscript with typescript [`2683c28`](https://github.com/bas080/sendscript/commit/2683c2873b8c4833711cdb00c777792c0630954a)
+- Improve naming of promise helper [`e177f39`](https://github.com/bas080/sendscript/commit/e177f39c740bc16864f1ed4fc90a6daa3321751f)
+
 #### [v0.1.0](https://github.com/bas080/sendscript/compare/v0.0.4...v0.1.0)
 
+> 21 October 2023
+
 - Allow nesting arrays, calls and args [`48e5804`](https://github.com/bas080/sendscript/commit/48e5804891db0ee0ed8c274f20f81d49d6609a54)
 
 #### [v0.0.4](https://github.com/bas080/sendscript/compare/v0.0.3...v0.0.4)

package/README.md

@@ -16,6 +16,7 @@ Write JS code that you can run on servers, browsers or other clients.
 - [Reference](#reference)
   * [`sendscript/api.mjs`](#sendscriptapimjs)
   * [`sendscript/exec.mjs`](#sendscriptexecmjs)
+- [TypeScript](#typescript)
 - [Tests](#tests)
 - [Formatting](#formatting)
 - [Changelog](#changelog)
@@ -184,6 +185,44 @@ The array you see here is the LISP that SendScript uses to represent programs.
 You could use SendScript without knowing the details of how the LISP works. It
 is an implementation detail and might change over time.
 
+## TypeScript
+
+There is a good use-case to write an environment module in TypeScript.
+
+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 generate a .d.ts with `tsc --declaration` and use it to coerce your
+   client to adopt the modules type.
+
+```bash
+# Create pretty docs for your module.
+npx typedoc my-module.ts
+
+# Create the .d.ts file for your module.
+tsc --declaration
+```
+
+Now we can use the `my-module.d.ts` file for the client API.
+
+```ts
+import type * as MyModule from './my-module.d.ts'
+
+import sendScriptApi from 'sendscript/api.mjs'
+
+export default sendScriptApi([
+  fnOne,
+  fnTwo,
+], /* perform websocket request */) as typeof MyModule
+```
+
+> [!NOTE]
+> Although type coercion on the client side can improve the development
+> experience, it does not represent the actual type.
+> Values are likely subject to serialization and deserialization,
+> particularly when interfacing with JSON formats.
+
 ## Tests
 
 Tests with 100% code coverage.
@@ -194,19 +233,19 @@ npm t -- report text-summary
 ```
 ```
 
-> sendscript@0.1.0 test
+> sendscript@0.1.2 test
 > tap -R silent
 
 
-> sendscript@0.1.0 test
+> sendscript@0.1.2 test
 > tap report text-summary
 
 
 =============================== Coverage summary ===============================
-Statements   : 100% ( 92/92 )
+Statements   : 100% ( 98/98 )
 Branches     : 100% ( 30/30 )
 Functions    : 100% ( 10/10 )
-Lines        : 100% ( 92/92 )
+Lines        : 100% ( 98/98 )
 ================================================================================
 ```
 
@@ -246,3 +285,4 @@ See the [LICENSE.txt][license] file for details.
 [socket.io]:https://socket.io/
 [changelog]:./CHANGELOG.md
 [auto-changelog]:https://www.npmjs.com/package/auto-changelog
+[typedoc]:https://github.com/TypeStrong/typedoc

package/README.mz

@@ -166,6 +166,44 @@ The array you see here is the LISP that SendScript uses to represent programs.
 You could use SendScript without knowing the details of how the LISP works. It
 is an implementation detail and might change over time.
 
+## TypeScript
+
+There is a good use-case to write an environment module in TypeScript.
+
+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 generate a .d.ts with `tsc --declaration` and use it to coerce your
+   client to adopt the modules type.
+
+```bash
+# Create pretty docs for your module.
+npx typedoc my-module.ts
+
+# Create the .d.ts file for your module.
+tsc --declaration
+```
+
+Now we can use the `my-module.d.ts` file for the client API.
+
+```ts
+import type * as MyModule from './my-module.d.ts'
+
+import sendScriptApi from 'sendscript/api.mjs'
+
+export default sendScriptApi([
+  fnOne,
+  fnTwo,
+], /* perform websocket request */) as typeof MyModule
+```
+
+> [!NOTE]
+> Although type coercion on the client side can improve the development
+> experience, it does not represent the actual type.
+> Values are likely subject to serialization and deserialization,
+> particularly when interfacing with JSON formats.
+
 ## Tests
 
 Tests with 100% code coverage.
@@ -208,3 +246,4 @@ See the [LICENSE.txt][license] file for details.
 [socket.io]:https://socket.io/
 [changelog]:./CHANGELOG.md
 [auto-changelog]:https://www.npmjs.com/package/auto-changelog
+[typedoc]:https://github.com/TypeStrong/typedoc

package/api.mjs

@@ -1,22 +1,30 @@
-import promiseOnly from './promise-only.mjs'
+import awaitWhen from './await-when.mjs'
 
 const symbol = Symbol('api')
-const isNonAPI = v => v?.[symbol] !== symbol
-const promiseOnlyNonAPI = promiseOnly(isNonAPI)
+const isNotStub = v => v?.[symbol] !== symbol
+const awaitWhenNotStub = awaitWhen(isNotStub)
 
+/**
+ * Create stubs to be used to build the program.
+ *
+ * @param {string[]} schema - Names of stubs.
+ * @param {Function} call - Function to call when awaited.
+ *
+ * @return {Object} An object containing the named stubs.
+ */
 export default function api (schema, call) {
   return schema.reduce((api, name) => {
     const then = (program) => (resolve, reject) =>
       Promise.resolve(call(program)).then(resolve, reject)
 
     const fn = (...args) => {
-      const toJSON = () => ['call', fn, ...args]
+      const toJSON = () => ['call', fn, args]
 
       return {
         [symbol]: symbol,
         toJSON,
         async then (resolve, reject) {
-          return then(await promiseOnlyNonAPI(toJSON()))(resolve, reject)
+          return then(await awaitWhenNotStub(toJSON()))(resolve, reject)
         }
       }
     }

package/{promise-only.mjs → await-when.mjs}

@@ -1,6 +1,6 @@
 import curry from './curry.mjs'
 
-const promiseOnly = curry(function promiseOnly (when, array) {
+export default curry(function awaitWhen (when, array) {
   return array.reduce(async (asyncAcc, item) => {
     const acc = await asyncAcc
 
@@ -9,5 +9,3 @@ const promiseOnly = curry(function promiseOnly (when, array) {
     return acc
   }, [])
 })
-
-export default promiseOnly

package/exec.mjs

@@ -13,9 +13,9 @@ const exec = curry(async (env, expression) => {
   const [operator, ...args] = expression
 
   if (operator === 'call') {
-    const [fnName, ...fnArgs] = args
+    const [fnRef, fnArgs] = args
 
-    const fn = await exec(env, fnName)
+    const fn = await exec(env, fnRef)
     return fn.apply(env, await exec(env, fnArgs))
   }
 

package/exec.test.mjs

@@ -18,6 +18,11 @@ test('should evaluate basic expressions correctly', async (t) => {
     3
   )
 
+  t.strictSame(
+    await evaluate([]),
+    []
+  )
+
   t.strictSame(
     await evaluate(concat([1, 2], [[add(1, 2)]])),
     [1, 2, [3]]

package/package.json

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

package/schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "JSON S-expression Language Schema",
+  "description": "Schema for a custom JSON S-expression language.",
+  "definitions": {
+    "ref": {
+      "title": "Reference Operator",
+      "description": "A reference to a function or identifier.",
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 2,
+      "items": [
+        { "enum": ["ref"], "title": "Operator", "description": "The operator type, representing a reference to a function or identifier." },
+        { "type": "string", "title": "Identifier", "description": "The identifier or function name." }
+      ]
+    },
+    "call": {
+      "title": "Call Operator",
+      "description": "A function call.",
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 3,
+      "items": [
+        { "const": "call", "title": "Operator", "description": "The operator type, representing a function call." },
+        { "$ref": "#/definitions/ref", "title": "Reference", "description": "The reference to a function or identifier." },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#"
+          },
+          "title": "Arguments",
+          "description": "The arguments passed to the function."
+        }
+      ]
+    }
+  },
+  "oneOf": [
+    { "$ref": "#/definitions/ref" },
+    { "$ref": "#/definitions/call" },
+    { "type": "number", "title": "Number", "description": "A JSON number." },
+    { "type": "string", "title": "String", "description": "A JSON string." },
+    { "type": "boolean", "title": "Boolean", "description": "A JSON boolean." },
+    { "type": "null", "title": "Null", "description": "A JSON null value." },
+    {
+      "title": "Object",
+      "description": "A generic JSON object with additional properties.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#"
+      }
+    }
+  ]
+}