sendscript 0.0.0 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+### Changelog
+
+All notable changes to this project will be documented in this file. Dates are displayed in UTC.
+
+Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
+
+#### [v0.0.2](https://github.com/bas080/sendscript/compare/v0.0.1...v0.0.2)
+
+- Add table of content to readme [`a14f2d8`](https://github.com/bas080/sendscript/commit/a14f2d86f602a01721812d1c5be94b299e515397)
+
+#### [v0.0.1](https://github.com/bas080/sendscript/compare/v0.0.0...v0.0.1)
+
+> 26 September 2023
+
+- Add square fn to the socket.io example [`8d7cfbd`](https://github.com/bas080/sendscript/commit/8d7cfbddd7933804e7168825cf1e17e792c91fe9)
+- Rename dsl to api [`4a67324`](https://github.com/bas080/sendscript/commit/4a6732456656db743d02c5c35444f93a866d27ec)
+- Move promise only concept to own module [`50adde6`](https://github.com/bas080/sendscript/commit/50adde694b3d23fb025a4ad20dcc83d7bb72b852)
+
+#### v0.0.0
+
+> 14 September 2023
+
+- Initiate project [`2a192b3`](https://github.com/bas080/sendscript/commit/2a192b34e5390ab946b7b77fd299e23180c49f72)

package/README.md

@@ -3,11 +3,29 @@
 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)
+[![100% Code Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square)](#tests)
 [![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)
+[![License](https://img.shields.io/npm/l/sendscript?color=brightgreen&style=flat-square)](./LICENSE.txt)
 
-> 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.
+
+<!-- toc -->
+
+- [Socket example](#socket-example)
+  * [Module](#module)
+  * [Server](#server)
+  * [Client](#client)
+- [Reference](#reference)
+  * [`sendscript/api.mjs`](#sendscriptapimjs)
+  * [`sendscript/exec.mjs`](#sendscriptexecmjs)
+- [Tests](#tests)
+- [Formatting](#formatting)
+- [Changelog](#changelog)
+- [License](#license)
+
+<!-- tocstop -->
 
 ## Socket example
 
@@ -21,17 +39,18 @@ npm install --no-save socket.io socket.io-client
 
 ### Module
 
-We write a simple module that only has an add function
+We write a simple module.
 
 ```js
 // ./example/math.mjs
 
 export const add = (a, b) => a + b
+export const square = a => a * a
 ```
 
 ### Server
 
-Here a simple module for running a socket.io server that runs SendScript programs.
+Here a socket.io server that runs SendScript programs.
 
 ```js
 // ./example/server.socket.io.mjs
@@ -66,7 +85,7 @@ Now for a client that sends a program to the server.
 // ./example/client.socket.io.mjs
 
 import socketClient from 'socket.io-client'
-import dsl from '../dsl.mjs'
+import api from '../api.mjs'
 
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
@@ -81,10 +100,10 @@ const exec = program => {
   })
 }
 
-const { add } = dsl(['add'], exec)
+const { add, square } = api(['add', 'square'], exec)
 
 console.log(
-  await add(1, add(add(2, 3), 4))
+  await square(add(1, add(add(2, 3), 4)))
 )
 
 process.exit(0)
@@ -102,33 +121,33 @@ node ./example/client.socket.io.mjs
 pkill sendscript
 ```
 ```
-10
+100
 ```
 
 ## Reference
 
-SendScript is essentially a way to serialize a program to then send over the wire
-and execute it somewhere else.
+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`
+### `sendscript/api.mjs`
 
-The dsl module exports a function that takes two arguments.
+The api 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
+These functions are a JavaScript API for writing programs that can be sent to
 a server.
 
 ```js
-import dsl from './dsl.mjs'
+import api from './api.mjs'
 
-const  { add, subtract } = dsl(
+const  { add, subtract } = api(
   ['add', 'subtract'],
   serializableProgram => sendSomewhereToBeExecuted(serializableProgram)
 )
@@ -144,7 +163,7 @@ 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.
+This API is composable and wrappable.
 
 ### `sendscript/exec.mjs`
 
@@ -161,8 +180,8 @@ exec({
 
 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.
+You could use SendScript without knowing the details of how the LISP works. It
+is an implementation detail and might change over time.
 
 ## Tests
 
@@ -173,27 +192,28 @@ npx c8 --100 npm t -- -R classic
 ```
 ```
 
-> sendscript@0.0.0 test
+> sendscript@0.0.2 test
 > tap *.test.mjs --no-cov -R classic
 
+api.test.mjs .......................................... 5/5
 curry.test.mjs ........................................ 4/4
-dsl.test.mjs .......................................... 5/5
-exec.test.mjs ....................................... 15/15
-total ............................................... 24/24
+exec.test.mjs ....................................... 16/16
+total ............................................... 25/25
 
-  24 passing (400.194ms)
+  25 passing (426.12ms)
 
   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 |                   
------------|---------|----------|---------|---------|-------------------
+------------------|---------|----------|---------|---------|-------------------
+File              | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
+------------------|---------|----------|---------|---------|-------------------
+All files         |     100 |      100 |     100 |     100 |                   
+ api.mjs          |     100 |      100 |     100 |     100 |                   
+ curry.mjs        |     100 |      100 |     100 |     100 |                   
+ debug.mjs        |     100 |      100 |     100 |     100 |                   
+ error.mjs        |     100 |      100 |     100 |     100 |                   
+ exec.mjs         |     100 |      100 |     100 |     100 |                   
+ promise-only.mjs |     100 |      100 |     100 |     100 |                   
+------------------|---------|----------|---------|---------|-------------------
 ```
 
 ## Formatting

package/README.mz

@@ -3,11 +3,15 @@
 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)
+[![100% Code Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square)](#tests)
 [![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)
+[![License](https://img.shields.io/npm/l/sendscript?color=brightgreen&style=flat-square)](./LICENSE.txt)
 
-> 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.
+
+<!-- toc -->
 
 ## Socket example
 
@@ -21,17 +25,18 @@ npm install --no-save socket.io socket.io-client
 
 ### Module
 
-We write a simple module that only has an add function
+We write a simple module.
 
 ```js cat - > ./example/math.mjs
 // ./example/math.mjs
 
 export const add = (a, b) => a + b
+export const square = a => a * a
 ```
 
 ### Server
 
-Here a simple module for running a socket.io server that runs SendScript programs.
+Here a socket.io server that runs SendScript programs.
 
 ```js cat - > ./example/server.socket.io.mjs
 // ./example/server.socket.io.mjs
@@ -66,7 +71,7 @@ Now for a client that sends a program to the server.
 // ./example/client.socket.io.mjs
 
 import socketClient from 'socket.io-client'
-import dsl from '../dsl.mjs'
+import api from '../api.mjs'
 
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
@@ -81,10 +86,10 @@ const exec = program => {
   })
 }
 
-const { add } = dsl(['add'], exec)
+const { add, square } = api(['add', 'square'], exec)
 
 console.log(
-  await add(1, add(add(2, 3), 4))
+  await square(add(1, add(add(2, 3), 4)))
 )
 
 process.exit(0)
@@ -104,28 +109,28 @@ pkill sendscript
 
 ## Reference
 
-SendScript is essentially a way to serialize a program to then send over the wire
-and execute it somewhere else.
+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`
+### `sendscript/api.mjs`
 
-The dsl module exports a function that takes two arguments.
+The api 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
+These functions are a JavaScript API for writing programs that can be sent to
 a server.
 
 ```js
-import dsl from './dsl.mjs'
+import api from './api.mjs'
 
-const  { add, subtract } = dsl(
+const  { add, subtract } = api(
   ['add', 'subtract'],
   serializableProgram => sendSomewhereToBeExecuted(serializableProgram)
 )
@@ -141,7 +146,7 @@ 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.
+This API is composable and wrappable.
 
 ### `sendscript/exec.mjs`
 
@@ -158,8 +163,8 @@ exec({
 
 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.
+You could use SendScript without knowing the details of how the LISP works. It
+is an implementation detail and might change over time.
 
 ## Tests
 

package/api.mjs

@@ -0,0 +1,32 @@
+import promiseOnly from './promise-only.mjs'
+
+const symbol = Symbol('api')
+const isNonAPI = v => v?.[symbol] !== symbol
+const promiseOnlyNonAPI = promiseOnly(isNonAPI)
+
+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)
+      }
+    })
+
+    fn.toJSON = () => ['ref', name]
+    fn.then = then(fn)
+    fn[symbol] = symbol
+
+    api[name] = fn
+
+    return api
+  }, {})
+}

package/{dsl.test.mjs → api.test.mjs}

@@ -1,10 +1,10 @@
 import { test } from 'tap'
-import dsl from './dsl.mjs'
+import api from './api.mjs'
 
 test('return a constant value', async t => {
   t.plan(1)
 
-  const { constant } = dsl(['constant'], v => {
+  const { constant } = api(['constant'], v => {
     t.equal(JSON.stringify(v), '["ref","constant"]')
   })
 
@@ -14,7 +14,7 @@ test('return a constant value', async t => {
 test('use function calls as arguments', async t => {
   t.plan(4)
 
-  const { add } = dsl(['add'], b => {
+  const { add } = api(['add'], b => {
     t.equal(JSON.stringify(awaited), JSON.stringify(b))
     return 'done'
   })

package/example/client.socket.io.mjs

@@ -1,7 +1,7 @@
 // ./example/client.socket.io.mjs
 
 import socketClient from 'socket.io-client'
-import dsl from '../dsl.mjs'
+import api from '../api.mjs'
 
 const port = process.env.PORT || 3000
 const client = socketClient(`http://localhost:${port}`)
@@ -16,10 +16,10 @@ const exec = program => {
   })
 }
 
-const { add } = dsl(['add'], exec)
+const { add, square } = api(['add', 'square'], exec)
 
 console.log(
-  await add(1, add(add(2, 3), 4))
+  await square(add(1, add(add(2, 3), 4)))
 )
 
 process.exit(0)

package/example/math.mjs

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

package/exec.test.mjs

@@ -108,3 +108,18 @@ test('should reject with the error of the called function', async t => {
 
   t.end()
 })
+
+test('should not exec expressions in an object', async t => {
+  const env = {
+    throws () {
+      throw new Error('Should not have been called.')
+    }
+  }
+
+  const result = await exec(env, { quoted: ['throws'] })
+
+  t.same(result, {
+    quoted: ['throws']
+  })
+  t.end()
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sendscript",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "Blur the line between server and client code.",
   "module": true,
   "main": "index.mjs",
@@ -11,7 +11,7 @@
   "scripts": {
     "test": "tap *.test.mjs --no-cov",
     "version": "npm run docs && git add *.md",
-    "docs": "markatzea README.mz | tee README.md"
+    "docs": "markatzea README.mz | tee README.md && npx markdown-toc -i README.md"
   },
   "author": "Bas Huis",
   "license": "MIT",

package/promise-only.mjs

@@ -0,0 +1,13 @@
+import curry from './curry.mjs'
+
+const promiseOnly = curry(function promiseOnly (when, array) {
+  return array.reduce(async (asyncAcc, item) => {
+    const acc = await asyncAcc
+
+    acc.push(when(item) ? await item : item)
+
+    return acc
+  }, [])
+})
+
+export default promiseOnly

package/dsl.mjs

@@ -1,40 +0,0 @@
-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
-  }, {})
-}