sendscript 0.0.4 → 0.1.1

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.1](https://github.com/bas080/sendscript/compare/v0.1.0...v0.1.1)
+
+- 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)
 
+> 6 October 2023
+
 - Add keywords to package.json [`e24d77b`](https://github.com/bas080/sendscript/commit/e24d77b14e67399cedc085294fbef3024a060087)
 - Add .tap to gitignore [`d0abbca`](https://github.com/bas080/sendscript/commit/d0abbcaafab8b915449118b3d2926ca7ff8dc133)
 

package/README.md

@@ -16,11 +16,11 @@ 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)
 - [Dependencies](#dependencies)
-- [License](#license)
 
 <!-- tocstop -->
 
@@ -184,6 +184,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 +232,19 @@ npm t -- report text-summary
 ```
 ```
 
-> sendscript@0.0.4 test
+> sendscript@0.1.1 test
 > tap -R silent
 
 
-> sendscript@0.0.4 test
+> sendscript@0.1.1 test
 > tap report text-summary
 
 
 =============================== Coverage summary ===============================
-Statements   : 100% ( 139/139 )
-Branches     : 100% ( 47/47 )
-Functions    : 100% ( 12/12 )
-Lines        : 100% ( 139/139 )
+Statements   : 100% ( 98/98 )
+Branches     : 100% ( 30/30 )
+Functions    : 100% ( 10/10 )
+Lines        : 100% ( 98/98 )
 ================================================================================
 ```
 
@@ -235,14 +273,6 @@ Check if packages are up to date on release.
 npm outdated && echo 'No outdated packages found'
 ```
 ```
-No outdated packages found
+Package  Current  Wanted  Latest  Location          Depended by
+tap       18.5.2  18.6.1  18.6.1  node_modules/tap  sendscript
 ```
-
-## License
-
-See the [LICENSE.txt][license] file for details.
-
-[license]:./LICENSE.txt
-[socket.io]:https://socket.io/
-[changelog]:./CHANGELOG.md
-[auto-changelog]:https://www.npmjs.com/package/auto-changelog

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,25 +1,33 @@
-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) => ({
-      [symbol]: symbol,
-      toJSON () {
-        return [fn, ...args]
-      },
-      async then (resolve, reject) {
-        return then(await promiseOnlyNonAPI([
-          fn, ...args
-        ]))(resolve, reject)
+    const fn = (...args) => {
+      const toJSON = () => ['call', fn, args]
+
+      return {
+        [symbol]: symbol,
+        toJSON,
+        async then (resolve, reject) {
+          return then(await awaitWhenNotStub(toJSON()))(resolve, reject)
+        }
       }
-    })
+    }
 
     fn.toJSON = () => ['ref', name]
     fn.then = then(fn)

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

@@ -1,11 +1,7 @@
 import _debug from './debug.mjs'
-import { BlendExpressionError } from './error.mjs'
 import curry from './curry.mjs'
 
 const debug = _debug.extend('lisp')
-const debugError = debug.extend('error')
-const isFunction = x => typeof x === 'function'
-const castFunction = x => isFunction(x) ? x : () => x
 
 const exec = curry(async (env, expression) => {
   debug('exec', expression)
@@ -16,54 +12,20 @@ const exec = curry(async (env, expression) => {
 
   const [operator, ...args] = expression
 
-  // Yey, resolved and all and ready to call.
-  if (isFunction(operator)) {
-    try {
-      return await operator.call(env, ...(await Promise.all(args.map(exec(env)))))
-    } catch (error) {
-      debugError(error)
-      throw error
-    }
-  }
-
-  // Use JSON value when toJSON is implemented.
-  // NECESSARY? if (operator?.toJSON) { operator = operator.toJSON() }
-
-  if (operator === 'fn') {
-    const [body] = args
-
-    return (fnEnv) => exec(Object.assign(Object.create(env), fnEnv), body)
-  }
-
-  if (operator === 'let') {
-    const letEnv = Object.create(env)
-    const [letBindings, letBody] = args
+  if (operator === 'call') {
+    const [fnRef, fnArgs] = args
 
-    await Promise.all(letBindings.map(async ([name, letExpr]) => {
-      letEnv[name] = await exec(letEnv, letExpr)
-    }))
-
-    return exec(letEnv, letBody)
+    const fn = await exec(env, fnRef)
+    return fn.apply(env, await exec(env, fnArgs))
   }
 
   if (operator === 'ref') {
     const [name] = args
-    return env[name]
-  }
 
-  if (Array.isArray(operator)) {
-    return exec(env, [await exec(env, operator), ...args])
-  }
-
-  // Throw error if operator is not in env.
-  if (!(operator in env)) {
-    const error = new BlendExpressionError(`Unknown expression: ${operator}`)
-    debugError(error)
-    throw error
+    return env[name]
   }
 
-  return exec(env, [castFunction(env[operator]), ...args])
+  return await Promise.all(expression.map(exec(env)))
 })
 
-export { exec }
 export default exec

package/exec.test.mjs

@@ -1,125 +1,42 @@
 import { test } from 'tap'
-import { exec } from './exec.mjs'
+import api from './api.mjs'
+import exec from './exec.mjs'
 
-test('should evaluate basic expressions correctly', (t) => {
-  t.plan(4)
-
-  exec({ '+': (a, b) => a + b }, ['+', 1, 2])
-    .then((result) => t.equal(result, 3, '1 + 2 = 3'))
-
-  exec({ '-': (a, b) => a - b }, ['-', 5, 3])
-    .then((result) => t.equal(result, 2, '5 - 3 = 2'))
-
-  exec({ '*': (a, b) => a * b }, ['*', 4, 3])
-    .then((result) => t.equal(result, 12, '4 * 3 = 12'))
-
-  exec({ '/': (a, b) => a / b }, ['/', 10, 2])
-    .then((result) => t.equal(result, 5, '10 / 2 = 5'))
-})
-
-test('should be able to call a partially applied function', async t => {
-  const env = {
-    '+': a => b => a + b
-  }
-
-  t.equal(typeof (await exec(env, ['+', 1])), 'function')
-  t.equal(await exec(env, [['+', 1], 2]), 3)
-  t.end()
-})
-
-test('should handle let expressions', (t) => {
-  t.plan(1)
-
-  exec({ '+': (a, b) => a + b }, ['let', [['x', 2], ['y', 3]], ['+', ['x'], ['y']]])
-    .then((result) => t.equal(result, 5, 'x + y = 5'))
-})
-
-test('should handle fn expressions', (t) => {
-  t.plan(2)
-
-  exec({}, ['fn', ['+', 1, 'x']])
-    .then((result) => t.equal(typeof result, 'function', 'should return a function'))
-
-  exec({ '+': (a, b) => a + b }, ['fn', ['+', 1, ['x']]])
-    .then(async (result) => {
-      t.equal(await result({ x: 2 }), 3, '1 + 2 = 3')
-    })
-})
-
-test('should throw an error for unknown expressions', (t) => {
-  t.plan(1)
-
-  exec({ '+': (a, b) => a + b }, ['-', 1, 2])
-    .catch((err) => t.equal(err.message, 'Unknown expression: -', 'should throw an error for unknown expressions'))
-})
-
-test('should evaluate nested expressions correctly', (t) => {
-  t.plan(1)
-
-  const env = {
-    '+': (a, b) => a + b,
-    '*': (a, b) => a * b
-  }
-
-  exec(env, ['*', 2, ['+', 1, 2]])
-    .then((result) => t.equal(result, 6, '2 * (1 + 2) = 6'))
-})
-
-test('should concatenate two arrays', async t => {
-  t.plan(1)
-
-  const env = {
-    array: (...args) => args,
+test('should evaluate basic expressions correctly', async (t) => {
+  const module = {
+    add: (a, b) => a + b,
+    identity: x => x,
     concat: (a, b) => a.concat(b)
   }
-  const expression = ['concat', ['array', 1, 2, 3], ['array', 4, 5, 6]]
-  const result = await exec(env, expression)
-
-  t.same(result, [1, 2, 3, 4, 5, 6])
-})
-
-test('should fetch the reference to the item on the env', async t => {
-  const value = 'yey'
-
-  const env = {
-    thing: () => value
-  }
-
-  const expression = ['ref', 'thing']
-  const result = await exec(env, expression)
-
-  t.same(result(), value)
 
-  const result2 = await exec(env, ['thing'])
-  t.same(result2, value)
-
-  t.end()
-})
+  const evaluate = exec(module)
+  const { add, concat, identity } = api(Object.keys(module), program =>
+    evaluate(JSON.parse(JSON.stringify(program))))
 
-test('should reject with the error of the called function', async t => {
-  const error = new Error('BOOM')
-  const env = {
-    throws () {
-      throw error
-    }
-  }
+  t.equal(
+    await evaluate(add(1, 2)),
+    3
+  )
 
-  await t.rejects(exec(env, ['throws']))
+  t.strictSame(
+    await evaluate([]),
+    []
+  )
 
-  t.end()
-})
+  t.strictSame(
+    await evaluate(concat([1, 2], [[add(1, 2)]])),
+    [1, 2, [3]]
+  )
 
-test('should not exec expressions in an object', async t => {
-  const env = {
-    throws () {
-      throw new Error('Should not have been called.')
-    }
-  }
+  t.strictSame(
+    await evaluate(concat([1, 2], [add(1, 2), add(2, 2)])),
+    [1, 2, 3, 4]
+  )
 
-  const result = await exec(env, { quoted: ['throws'] })
+  t.strictSame(
+    await evaluate([identity(1), 2, 3]),
+    [1, 2, 3]
+  )
 
-  t.same(result, {
-    quoted: ['throws']
-  })
   t.end()
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sendscript",
-  "version": "0.0.4",
+  "version": "0.1.1",
   "description": "Blur the line between server and client code.",
   "module": true,
   "main": "index.mjs",
@@ -23,7 +23,7 @@
   "author": "Bas Huis",
   "license": "MIT",
   "devDependencies": {
-    "tap": "^18.4.3"
+    "tap": "^18.5.2"
   },
   "dependencies": {
     "debug": "^4.3.4"

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": "#"
+      }
+    }
+  ]
+}

package/api.test.mjs

@@ -1,31 +0,0 @@
-import { test } from 'tap'
-import api from './api.mjs'
-
-test('return a constant value', async t => {
-  t.plan(1)
-
-  const { constant } = api(['constant'], v => {
-    t.equal(JSON.stringify(v), '["ref","constant"]')
-  })
-
-  await constant
-})
-
-test('use function calls as arguments', async t => {
-  t.plan(4)
-
-  const { add } = api(['add'], b => {
-    t.equal(JSON.stringify(awaited), JSON.stringify(b))
-    return 'done'
-  })
-
-  const program = add(add(add(1, 2), 3), 4)
-  const awaited = program
-  const thenned = program
-
-  t.equal(await awaited, 'done')
-
-  await thenned.then(result => {
-    t.equal(result, 'done')
-  })
-})