sendscript 0.0.0

package/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright © 2023
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# SendScript
+
+Write JS code that you can run on servers, browsers or other clients.
+
+[![NPM](https://img.shields.io/npm/v/sendscript?color=blue&style=flat-square)](https://www.npmjs.com/package/sendscript)
+[![Standard Code Style](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](https://standardjs.com)
+[![License](https://img.shields.io/npm/l/sendscript?color=brightgreen&style=flat-square)](./LICENSE)
+
+> 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.
+
+## Socket example
+
+For this example we'll use [socket.io][socket.io].
+
+```bash
+npm install --no-save socket.io socket.io-client
+```
+
+> We use the `--no-save` option because it's only for demonstration purposes.
+
+### Module
+
+We write a simple module that only has an add function
+
+```js
+// ./example/math.mjs
+
+export const add = (a, b) => a + b
+```
+
+### Server
+
+Here a simple module for running a socket.io server that runs SendScript programs.
+
+```js
+// ./example/server.socket.io.mjs
+
+import { Server } from 'socket.io'
+import exec from '../exec.mjs'
+import * as math from './math.mjs'
+
+const server = new Server()
+const port = process.env.PORT || 3000
+
+server.on('connection', (socket) => {
+  socket.on('message', async (program, callback) => {
+    try {
+      const result = await exec(math, program)
+      callback(null, result) // Pass null as the first argument to indicate success
+    } catch (error) {
+      callback(error) // Pass the error to the callback
+    }
+  })
+})
+
+server.listen(port)
+process.title = 'sendscript'
+```
+
+### Client
+
+Now for a client that sends a program to the server.
+
+```js
+// ./example/client.socket.io.mjs
+
+import socketClient from 'socket.io-client'
+import dsl from '../dsl.mjs'
+
+const port = process.env.PORT || 3000
+const client = socketClient(`http://localhost:${port}`)
+
+const exec = program => {
+  return new Promise((resolve, reject) => {
+    client.emit('message', program, (error, result) => {
+      error
+        ? reject(error)
+        : resolve(result)
+    })
+  })
+}
+
+const { add } = dsl(['add'], exec)
+
+console.log(
+  await add(1, add(add(2, 3), 4))
+)
+
+process.exit(0)
+```
+
+Now we run this server and a client script.
+
+```bash
+# Run the server
+node ./example/server.socket.io.mjs&
+
+# Run the client example
+node ./example/client.socket.io.mjs
+
+pkill sendscript
+```
+```
+10
+```
+
+## Reference
+
+SendScript is essentially a way to serialize a program to then send over the wire
+and execute it somewhere else.
+
+We only have two modules. One that helps you write programs that can be sent
+over the wire and another for running that program.
+
+### `sendscript/dsl.mjs`
+
+The dsl module exports a function that takes two arguments.
+
+1. The schema, which represents the values that are available.
+2. The function that will be called with the serializable version of the
+   program.
+
+It returns an object that contains functions which are defined in the schema.
+These functions are a JavaScript DSL for writing programs that can be sent to
+a server.
+
+```js
+import dsl from './dsl.mjs'
+
+const  { add, subtract } = dsl(
+  ['add', 'subtract'],
+  serializableProgram => sendSomewhereToBeExecuted(serializableProgram)
+)
+
+await add(1, 2) // => 3
+await subtract(1, 2) // => -1
+await add(1, subtract(2, 3)) // => 0
+```
+
+The add and subtract functions are thennable. The execute function is called as
+soon as await or `.then` is used.
+
+> Notice that you do not have to await the subtract call. You only need to
+> await when you want to execute the program.
+
+This DSL is composable and wrappable.
+
+### `sendscript/exec.mjs`
+
+The exec function takes an environment object and any valid SendScript program.
+
+```js
+import exec from './exec.mjs'
+
+exec({
+  add: (a, b) => a + b,
+  subtract: (a, b) => a - b
+}, ['add', 1, [subtract, 1, 2]])
+```
+
+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.
+
+## Tests
+
+Tests with 100% code coverage.
+
+```bash
+npx c8 --100 npm t -- -R classic
+```
+```
+
+> sendscript@0.0.0 test
+> tap *.test.mjs --no-cov -R classic
+
+curry.test.mjs ........................................ 4/4
+dsl.test.mjs .......................................... 5/5
+exec.test.mjs ....................................... 15/15
+total ............................................... 24/24
+
+  24 passing (400.194ms)
+
+  ok
+-----------|---------|----------|---------|---------|-------------------
+File       | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
+-----------|---------|----------|---------|---------|-------------------
+All files  |     100 |      100 |     100 |     100 |                   
+ curry.mjs |     100 |      100 |     100 |     100 |                   
+ debug.mjs |     100 |      100 |     100 |     100 |                   
+ dsl.mjs   |     100 |      100 |     100 |     100 |                   
+ error.mjs |     100 |      100 |     100 |     100 |                   
+ exec.mjs  |     100 |      100 |     100 |     100 |                   
+-----------|---------|----------|---------|---------|-------------------
+```
+
+## Formatting
+
+Standard because no config.
+
+```bash
+npx standard
+```
+
+## Changelog
+
+The [changelog][changelog] is generated using the useful
+[auto-changelog][auto-changelog] project.
+
+```bash
+npx auto-changelog -p
+```
+
+## 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

@@ -0,0 +1,196 @@
+# SendScript
+
+Write JS code that you can run on servers, browsers or other clients.
+
+[![NPM](https://img.shields.io/npm/v/sendscript?color=blue&style=flat-square)](https://www.npmjs.com/package/sendscript)
+[![Standard Code Style](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](https://standardjs.com)
+[![License](https://img.shields.io/npm/l/sendscript?color=brightgreen&style=flat-square)](./LICENSE)
+
+> 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.
+
+## Socket example
+
+For this example we'll use [socket.io][socket.io].
+
+```bash bash > /dev/null
+npm install --no-save socket.io socket.io-client
+```
+
+> We use the `--no-save` option because it's only for demonstration purposes.
+
+### Module
+
+We write a simple module that only has an add function
+
+```js cat - > ./example/math.mjs
+// ./example/math.mjs
+
+export const add = (a, b) => a + b
+```
+
+### Server
+
+Here a simple module for running a socket.io server that runs SendScript programs.
+
+```js cat - > ./example/server.socket.io.mjs
+// ./example/server.socket.io.mjs
+
+import { Server } from 'socket.io'
+import exec from '../exec.mjs'
+import * as math from './math.mjs'
+
+const server = new Server()
+const port = process.env.PORT || 3000
+
+server.on('connection', (socket) => {
+  socket.on('message', async (program, callback) => {
+    try {
+      const result = await exec(math, program)
+      callback(null, result) // Pass null as the first argument to indicate success
+    } catch (error) {
+      callback(error) // Pass the error to the callback
+    }
+  })
+})
+
+server.listen(port)
+process.title = 'sendscript'
+```
+
+### Client
+
+Now for a client that sends a program to the server.
+
+```js cat - > ./example/client.socket.io.mjs
+// ./example/client.socket.io.mjs
+
+import socketClient from 'socket.io-client'
+import dsl from '../dsl.mjs'
+
+const port = process.env.PORT || 3000
+const client = socketClient(`http://localhost:${port}`)
+
+const exec = program => {
+  return new Promise((resolve, reject) => {
+    client.emit('message', program, (error, result) => {
+      error
+        ? reject(error)
+        : resolve(result)
+    })
+  })
+}
+
+const { add } = dsl(['add'], exec)
+
+console.log(
+  await add(1, add(add(2, 3), 4))
+)
+
+process.exit(0)
+```
+
+Now we run this server and a client script.
+
+```bash bash
+# Run the server
+node ./example/server.socket.io.mjs&
+
+# Run the client example
+node ./example/client.socket.io.mjs
+
+pkill sendscript
+```
+
+## Reference
+
+SendScript is essentially a way to serialize a program to then send over the wire
+and execute it somewhere else.
+
+We only have two modules. One that helps you write programs that can be sent
+over the wire and another for running that program.
+
+### `sendscript/dsl.mjs`
+
+The dsl module exports a function that takes two arguments.
+
+1. The schema, which represents the values that are available.
+2. The function that will be called with the serializable version of the
+   program.
+
+It returns an object that contains functions which are defined in the schema.
+These functions are a JavaScript DSL for writing programs that can be sent to
+a server.
+
+```js
+import dsl from './dsl.mjs'
+
+const  { add, subtract } = dsl(
+  ['add', 'subtract'],
+  serializableProgram => sendSomewhereToBeExecuted(serializableProgram)
+)
+
+await add(1, 2) // => 3
+await subtract(1, 2) // => -1
+await add(1, subtract(2, 3)) // => 0
+```
+
+The add and subtract functions are thennable. The execute function is called as
+soon as await or `.then` is used.
+
+> Notice that you do not have to await the subtract call. You only need to
+> await when you want to execute the program.
+
+This DSL is composable and wrappable.
+
+### `sendscript/exec.mjs`
+
+The exec function takes an environment object and any valid SendScript program.
+
+```js
+import exec from './exec.mjs'
+
+exec({
+  add: (a, b) => a + b,
+  subtract: (a, b) => a - b
+}, ['add', 1, [subtract, 1, 2]])
+```
+
+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.
+
+## Tests
+
+Tests with 100% code coverage.
+
+```bash bash
+npx c8 --100 npm t -- -R classic
+```
+
+## Formatting
+
+Standard because no config.
+
+```bash bash
+npx standard
+```
+
+## Changelog
+
+The [changelog][changelog] is generated using the useful
+[auto-changelog][auto-changelog] project.
+
+```bash bash > /dev/null
+npx auto-changelog -p
+```
+
+## 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/curry.mjs

@@ -0,0 +1,11 @@
+export default function curry (func) {
+  return function curried (...args) {
+    if (args.length >= func.length) {
+      return func.apply(this, args)
+    } else {
+      return function (...args2) {
+        return curried.apply(this, args.concat(args2))
+      }
+    }
+  }
+}

package/curry.test.mjs

@@ -0,0 +1,35 @@
+import { test } from 'tap'
+import curry from './curry.mjs'
+
+test('curry function', (t) => {
+  t.test('curry function returns a function', (assert) => {
+    const curried = curry((a, b, c) => a + b + c)
+    assert.type(curried, 'function', 'returns a function')
+    assert.end()
+  })
+
+  t.test('curried function returns correct result', (assert) => {
+    const curried = curry((a, b, c) => a + b + c)
+    const result = curried(1)(2)(3)
+    assert.equal(result, 6, 'returns correct result')
+    assert.end()
+  })
+
+  t.test('curried function handles partial application', (assert) => {
+    const curried = curry((a, b, c) => a + b + c)
+    const partial = curried(1, 2)
+    const result = partial(3)
+    assert.equal(result, 6, 'handles partial application')
+    assert.end()
+  })
+
+  t.test('curried function handles multiple arguments', (assert) => {
+    const curried = curry((a, b, c, d) => a + b + c + d)
+    const partial = curried(1)
+    const result = partial(2)(3, 4)
+    assert.equal(result, 10, 'handles multiple arguments')
+    assert.end()
+  })
+
+  t.end()
+})

package/debug.mjs

@@ -0,0 +1,5 @@
+import * as debug from 'debug'
+
+const { default: Debug } = debug
+
+export default Debug('sendscript')

package/dsl.mjs

@@ -0,0 +1,40 @@
+const symbol = Symbol('dsl')
+
+// Only await values that are not part of the dsl.
+const promiseAllNonDSL = async values => values.reduce(async (_acc, value) => {
+  const acc = await _acc
+
+  if (value[symbol] === symbol) {
+    acc.push(value)
+  } else {
+    acc.push(await value)
+  }
+
+  return acc
+}, [])
+
+export default function dsl (schema, call) {
+  return schema.reduce((api, name) => {
+    const then = (program) => (resolve, reject) =>
+      Promise.resolve(call(program)).then(resolve, reject)
+
+    const fn = (...args) => {
+      // Only await non dsl values
+      const v = [fn, ...args]
+
+      v[symbol] = symbol
+      v.then = async (...thenArgs) => {
+        return then(await promiseAllNonDSL(v))(...thenArgs)
+      }
+      return v
+    }
+
+    fn.toJSON = () => ['ref', name]
+    fn.then = then(fn)
+    fn[symbol] = symbol
+
+    api[name] = fn
+
+    return api
+  }, {})
+}

package/dsl.test.mjs

@@ -0,0 +1,31 @@
+import { test } from 'tap'
+import dsl from './dsl.mjs'
+
+test('return a constant value', async t => {
+  t.plan(1)
+
+  const { constant } = dsl(['constant'], v => {
+    t.equal(JSON.stringify(v), '["ref","constant"]')
+  })
+
+  await constant
+})
+
+test('use function calls as arguments', async t => {
+  t.plan(4)
+
+  const { add } = dsl(['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')
+  })
+})

package/error.mjs

@@ -0,0 +1,9 @@
+class BlendError extends Error { }
+class BlendExpressionError extends BlendError {}
+class BlendInvalidSchemaError extends BlendError {}
+
+export {
+  BlendError,
+  BlendExpressionError,
+  BlendInvalidSchemaError
+}

package/example/client.socket.io.mjs

@@ -0,0 +1,25 @@
+// ./example/client.socket.io.mjs
+
+import socketClient from 'socket.io-client'
+import dsl from '../dsl.mjs'
+
+const port = process.env.PORT || 3000
+const client = socketClient(`http://localhost:${port}`)
+
+const exec = program => {
+  return new Promise((resolve, reject) => {
+    client.emit('message', program, (error, result) => {
+      error
+        ? reject(error)
+        : resolve(result)
+    })
+  })
+}
+
+const { add } = dsl(['add'], exec)
+
+console.log(
+  await add(1, add(add(2, 3), 4))
+)
+
+process.exit(0)

package/example/math.mjs

@@ -0,0 +1,3 @@
+// ./example/math.mjs
+
+export const add = (a, b) => a + b

package/example/server.socket.io.mjs

@@ -0,0 +1,22 @@
+// ./example/server.socket.io.mjs
+
+import { Server } from 'socket.io'
+import exec from '../exec.mjs'
+import * as math from './math.mjs'
+
+const server = new Server()
+const port = process.env.PORT || 3000
+
+server.on('connection', (socket) => {
+  socket.on('message', async (program, callback) => {
+    try {
+      const result = await exec(math, program)
+      callback(null, result) // Pass null as the first argument to indicate success
+    } catch (error) {
+      callback(error) // Pass the error to the callback
+    }
+  })
+})
+
+server.listen(port)
+process.title = 'sendscript'

package/exec.mjs

@@ -0,0 +1,69 @@
+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)
+
+  if (!Array.isArray(expression)) {
+    return 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
+
+    await Promise.all(letBindings.map(async ([name, letExpr]) => {
+      letEnv[name] = await exec(letEnv, letExpr)
+    }))
+
+    return exec(letEnv, letBody)
+  }
+
+  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 exec(env, [castFunction(env[operator]), ...args])
+})
+
+export { exec }
+export default exec

package/exec.test.mjs

@@ -0,0 +1,110 @@
+import { test } from 'tap'
+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,
+    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()
+})
+
+test('should reject with the error of the called function', async t => {
+  const error = new Error('BOOM')
+  const env = {
+    throws () {
+      throw error
+    }
+  }
+
+  await t.rejects(exec(env, ['throws']))
+
+  t.end()
+})

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "sendscript",
+  "version": "0.0.0",
+  "description": "Blur the line between server and client code.",
+  "module": true,
+  "main": "index.mjs",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:bas080/sendscript.git"
+  },
+  "scripts": {
+    "test": "tap *.test.mjs --no-cov",
+    "version": "npm run docs && git add *.md",
+    "docs": "markatzea README.mz | tee README.md"
+  },
+  "author": "Bas Huis",
+  "license": "MIT",
+  "devDependencies": {
+    "tap": "^16.3.4"
+  },
+  "dependencies": {
+    "debug": "^4.3.4"
+  }
+}