sendscript 1.0.6 → 2.0.1

package/example/typescript/math.client.ts

@@ -1,9 +1,5 @@
-import module from 'sendscript/module.mjs'
 import type * as mathTypes from './math.ts'
+import Stringify from 'sendscript/stringify.mjs'
+import references from 'sendscript/references.mjs'
 
-const math = module([
-  'add',
-  'square'
-]) as typeof mathTypes
-
-export default math
+export default references(['add', 'square']) as typeof mathTypes

package/index.test.mjs

@@ -1,7 +1,14 @@
 import { test } from 'tap'
-import Sendscript from './index.mjs'
+import Stringify from './stringify.mjs'
+import references from './references.mjs'
+import Parse from './parse.mjs'
 
-const module = {
+const myModule = {
+  nested: {
+    again: {
+      T: () => true
+    }
+  },
   add: (a, b) => a + b,
   identity: (x) => x,
   concat: (a, b) => a.concat(b),
@@ -18,12 +25,23 @@ const module = {
   asyncAdd: async (a, b) => a + b,
   aPromise: Promise.resolve(42),
   delayedIdentity: async (x) => x,
-  Function,
+  nullProto: () => {
+    const obj = Object.create(null)
+    obj.b = 'c'
+    return obj
+  },
   Promise
 }
 
-const sendscript = Sendscript(module)
-const { parse, stringify } = sendscript
+const schema = Object.keys(myModule)
+schema.push(['nested', [
+  ['again', ['T']]
+]])
+
+const api = references(schema)
+const stringify = Stringify()
+const parse = Parse(schema, myModule)
+
 const run = (program) => parse(stringify(program))
 
 const RealPromise = Promise
@@ -35,7 +53,6 @@ test('should evaluate basic expressions correctly', async (t) => {
     resolve,
     delayedIdentity,
     noop,
-    Function,
     Promise,
     instanceOf,
     asyncFn,
@@ -46,8 +63,24 @@ test('should evaluate basic expressions correctly', async (t) => {
     concat,
     identity,
     always,
-    multiply3
-  } = sendscript.module
+    multiply3,
+    nested
+  } = api
+
+  t.test('mix await without await', async t => {
+    const [one, two] = await run([await resolve(1), resolve(2)])
+
+    t.equal(one, 1)
+    t.ok(two instanceof RealPromise)
+
+    t.end()
+  })
+
+  t.test('calling nested function works', t => {
+    t.equal(run(nested.again.T()), true)
+
+    t.end()
+  })
 
   t.test('nested await works', async (t) => {
     // Async identity passthrough
@@ -110,9 +143,6 @@ test('should evaluate basic expressions correctly', async (t) => {
     t.strictSame(await run(asyncFn()), 'my-async-function')
     t.strictSame(await run(await resolve('my-promise')), 'my-promise')
     t.strictSame(run(instanceOf(resolve(asyncFn), Promise)), true)
-    t.strictSame(
-      await run(instanceOf(await resolve(asyncFn), Function)), true
-    )
     t.strictSame(
       await run({ a: await resolve('b') }),
       { a: 'b' }
@@ -177,6 +207,16 @@ test('should evaluate basic expressions correctly', async (t) => {
       run(identity(['ref', 'hello'])),
       run(identity(toArray('ref', 'hello')))
     )
+    t.strictSame(
+      run(identity(['leaf', 1, 2, 3])),
+      ['leaf', 1, 2, 3]
+    )
+    t.end()
+  })
+
+  t.test('null-prototype object traversal', (t) => {
+    const { nullProto } = api
+    t.strictSame(run({ a: nullProto() }), { a: { b: 'c' } })
     t.end()
   })
 
@@ -195,3 +235,78 @@ test('should evaluate basic expressions correctly', async (t) => {
     t.end()
   })
 })
+
+test('stringify: invalid children throws', t => {
+  const invalidSchema = [
+    ['math', 'add']
+  ]
+
+  t.throws(() => Parse(invalidSchema, {}))
+  t.throws(() => Parse([Symbol('no-allowed')], {}))
+  t.end()
+})
+
+test('forbidden/reflection access should be blocked', async (t) => {
+  function run (program) {
+    return parse(JSON.stringify(program))
+  }
+
+  t.test('cannot access constructor via ref', (t) => {
+    // try to reach the constructor of nested.again.T
+    t.throws(() => run(['ref', 'nested', 'again', 'T', 'constructor']))
+    t.end()
+  })
+
+  t.test('cannot access prototype property', (t) => {
+    // direct prototype traversal attempt
+    t.throws(() => run(['ref', 'nested', '__proto__']))
+    t.throws(() => run(['ref', 'nested', 'again', '__proto__']))
+    t.end()
+  })
+
+  t.test('cannot reach Function constructor', (t) => {
+    // many modules may accidentally expose Function; this should not be available via ref
+    t.throws(() => run(['ref', 'Function']))
+    t.end()
+  })
+
+  t.test('cannot call Function to execute code', (t) => {
+    // If Function were reachable, this would execute arbitrary code
+    const program = ['call', ['ref', 'Function'], [['leaf', '"return 1 + 2"']]]
+    t.throws(() => run(program))
+    t.end()
+  })
+
+  t.test('cannot access global Promise constructor via ref', (t) => {
+    t.throws(() => run(['ref', 'Promise', 'prototype', 'then']))
+    t.end()
+  })
+
+  t.test('cannot access Object.prototype methods', (t) => {
+    // toString is a common vector for prototype access
+    t.throws(() => run(['ref', 'toString']))
+    t.throws(() => run(['ref', 'nested', 'again', 'T', 'toString']))
+    t.end()
+  })
+
+  t.test('cannot reach process or global (if accidentally exposed)', (t) => {
+    // attempt common global names; parser should not resolve them
+    t.throws(() => run(['ref', 'process']))
+    t.throws(() => run(['ref', 'global']))
+    t.end()
+  })
+
+  t.test('cannot use constructor.constructor to reach Function', (t) => {
+    // attempt: nested.again.T.constructor.constructor
+    t.throws(() => run(['ref', 'nested', 'again', 'T', 'constructor', 'constructor']))
+    t.end()
+  })
+
+  t.test('throws when trying to get something that does not exist', (t) => {
+    // Ensure array that contains a ref-like array stays as data if not a SendScript ref wrapper:
+    t.throws(() => run(['ref', 'doesNotExist']))
+    t.end()
+  })
+
+  t.end()
+})

package/leaf-serializer-property.test.mjs

@@ -0,0 +1,149 @@
+import { test } from 'tap'
+import { createRequire } from 'module'
+import SuperJSON from 'superjson'
+
+const require = createRequire(import.meta.url)
+const { check, gen } = require('tape-check')
+
+const leafSerializer = (value) => {
+  if (value === undefined) return JSON.stringify({ __sendscript_undefined__: true })
+  return JSON.stringify(SuperJSON.serialize(value))
+}
+
+const leafDeserializer = (text) => {
+  const parsed = JSON.parse(text)
+  if (parsed && parsed.__sendscript_undefined__ === true) return undefined
+  return SuperJSON.deserialize(parsed)
+}
+
+// Helper to compare values accounting for types that can't use ===
+const valueEquals = (a, b) => {
+  if (a === b) return true
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+  if (a instanceof RegExp && b instanceof RegExp) return a.source === b.source && a.flags === b.flags
+  if (a instanceof Set && b instanceof Set) {
+    if (a.size !== b.size) return false
+    for (const item of a) {
+      if (!b.has(item)) return false
+    }
+    return true
+  }
+  if (a instanceof Map && b instanceof Map) {
+    if (a.size !== b.size) return false
+    for (const [key, val] of a) {
+      if (!b.has(key) || !valueEquals(val, b.get(key))) return false
+    }
+    return true
+  }
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+// Helper to get a human-readable type name
+const getTypeInfo = (value) => {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (value instanceof Date) return 'Date'
+  if (value instanceof RegExp) return 'RegExp'
+  if (value instanceof Set) return 'Set'
+  if (value instanceof Map) return 'Map'
+  if (typeof value === 'bigint') return 'BigInt'
+  return typeof value
+}
+
+// Property 1: Round-trip - any value that can be serialized should deserialize to an equal value
+test('property: round-trip serialization preserves value', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    try {
+      const serialized = leafSerializer(value)
+      const deserialized = leafDeserializer(serialized)
+      const typeInfo = getTypeInfo(value)
+      t.ok(valueEquals(deserialized, value), `Round-trip preserved ${typeInfo}`)
+    } catch (e) {
+      // If serialization fails on a particular value, that's acceptable
+      // (not all values may be serializable)
+      const typeInfo = getTypeInfo(value)
+      t.pass(`Serialization of ${typeInfo} threw: ${e.message}`)
+    }
+  }
+))
+
+// Property 2: Determinism - serializing the same value repeatedly produces identical results
+test('property: serialization is deterministic', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    try {
+      const serialized1 = leafSerializer(value)
+      const serialized2 = leafSerializer(value)
+      const typeInfo = getTypeInfo(value)
+      t.equal(serialized1, serialized2, `Serialization of ${typeInfo} is deterministic`)
+    } catch (e) {
+      const typeInfo = getTypeInfo(value)
+      t.pass(`Serialization threw for ${typeInfo}: ${e.message}`)
+    }
+  }
+))
+
+// Property 3: Valid JSON - serialized output is always valid JSON
+test('property: serialized output is valid JSON', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    try {
+      const serialized = leafSerializer(value)
+      const parsed = JSON.parse(serialized)
+      t.ok(typeof parsed === 'object' || typeof parsed === 'string', 'Parsed JSON is an object or string')
+    } catch (e) {
+      t.fail(`Invalid JSON output for ${getTypeInfo(value)}: ${e.message}`)
+    }
+  }
+))
+
+// Property 4: Undefined handling - undefined values are preserved through round-trip
+test('property: undefined values are preserved through serialization', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    if (value === undefined) {
+      const serialized = leafSerializer(value)
+      const deserialized = leafDeserializer(serialized)
+      t.equal(deserialized, undefined, 'Undefined preserved through serialization')
+    } else {
+      t.pass('Value was not undefined')
+    }
+  }
+))
+
+// Property 5: Type distinctness - Different values should have different serializations (when possible)
+test('property: different primitives have different serializations', check(
+  gen.primitive,
+  gen.primitive,
+  (t, val1, val2) => {
+    t.plan(1)
+    if (val1 !== val2 && !(Number.isNaN(val1) && Number.isNaN(val2))) {
+      const ser1 = leafSerializer(val1)
+      const ser2 = leafSerializer(val2)
+      t.not(ser1, ser2, `Different primitives ${getTypeInfo(val1)} and ${getTypeInfo(val2)} have different serializations`)
+    } else {
+      t.pass('Primitives are equal or both NaN')
+    }
+  }
+))
+
+// Property 6: Idempotence of serialization - Re-parsing serialized value produces same serialization
+test('property: serialization round-trip is stable', check(
+  gen.any,
+  (t, value) => {
+    t.plan(1)
+    try {
+      const ser1 = leafSerializer(value)
+      const deser1 = leafDeserializer(ser1)
+      const ser2 = leafSerializer(deser1)
+      t.equal(ser1, ser2, `Serialization is stable for ${getTypeInfo(value)}`)
+    } catch (e) {
+      t.pass(`Serialization error for ${getTypeInfo(value)}: ${e.message}`)
+    }
+  }
+))

package/leaf-serializer.test.mjs

@@ -0,0 +1,71 @@
+import { test } from 'tap'
+import SuperJSON from 'superjson'
+import Parse from './parse.mjs'
+import Stringify from './stringify.mjs'
+
+const leafSerializer = (value) => {
+  if (value === undefined) return JSON.stringify({ __sendscript_undefined__: true })
+  return JSON.stringify(SuperJSON.serialize(value))
+}
+
+const leafDeserializer = (text) => {
+  const parsed = JSON.parse(text)
+  if (parsed && parsed.__sendscript_undefined__ === true) return undefined
+  return SuperJSON.deserialize(parsed)
+}
+
+const module = {
+  identity: (x) => x
+}
+
+const schema = Object.keys(module)
+
+const run = (program, serializer, deserializer) => {
+  const parse = Parse(schema, module, deserializer)
+  const stringify = Stringify(serializer)
+
+  return parse(stringify(program))
+}
+
+test('custom leaf serializer/deserializer using superjson', async (t) => {
+  const value = {
+    date: new Date('2020-01-01T00:00:00.000Z'),
+    regex: /abc/gi,
+    big: BigInt('123456789012345678901234567890'),
+    undef: undefined,
+    nested: {
+      set: new Set([1, 2, 3]),
+      map: new Map([['a', 1], ['b', 2]])
+    }
+  }
+
+  const result = await run(value, leafSerializer, leafDeserializer)
+
+  t.ok(result.date instanceof Date)
+  t.equal(result.date.toISOString(), value.date.toISOString())
+
+  t.ok(result.regex instanceof RegExp)
+  t.equal(result.regex.source, 'abc')
+  t.equal(result.regex.flags, 'gi')
+
+  t.equal(result.big, value.big)
+
+  t.ok(Object.prototype.hasOwnProperty.call(result, 'undef'))
+  t.equal(result.undef, undefined)
+
+  t.ok(result.nested.set instanceof Set)
+  t.strictSame(Array.from(result.nested.set), [1, 2, 3])
+
+  t.ok(result.nested.map instanceof Map)
+  t.strictSame(Array.from(result.nested.map.entries()), [['a', 1], ['b', 2]])
+
+  t.end()
+})
+
+test('default leaf deserializer when not provided', async (t) => {
+  const value = { a: 1, b: 'hello' }
+  const result = await run(value)
+
+  t.strictSame(result, value)
+  t.end()
+})

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "sendscript",
-  "version": "1.0.6",
+  "version": "2.0.1",
   "description": "Blur the line between server and client code.",
   "module": true,
   "main": "index.mjs",
+  "bin": "./cli.mjs",
   "keywords": [
     "rpc",
     "json",
@@ -23,9 +24,13 @@
   "author": "Bas Huis",
   "license": "MIT",
   "devDependencies": {
-    "tap": "^21.6.3"
+    "superjson": "^2.2.6",
+    "tap": "^21.6.3",
+    "tape-check": "^1.0.0-rc.0"
   },
   "dependencies": {
-    "debug": "^4.4.3"
+    "debug": "^4.4.3",
+    "typedoc": "^0.28.18",
+    "typedoc-plugin-markdown": "^4.11.0"
   }
 }

package/parse.mjs

@@ -1,43 +1,125 @@
 import Debug from './debug.mjs'
-import isNil from './is-nil.mjs'
 import { SendScriptReferenceError } from './error.mjs'
 
+function flattenSchema (schema) {
+  const obj = {}
+
+  for (const item of schema) {
+    if (typeof item === 'string') {
+      // leaf function
+      obj[item] = true
+    } else if (Array.isArray(item)) {
+      const [name, children] = item
+      // TODO: Test this
+      if (!Array.isArray(children)) {
+        throw new Error(`Expected children array for namespace "${name}"`)
+      }
+      obj[name] = flattenSchema(children)
+      // TODO: Test this also
+    } else {
+      throw new Error('Schema items must be strings or [name, children] arrays')
+    }
+  }
+
+  return obj
+}
+
 const debug = Debug.extend('parse')
 
-export default (env) =>
-  function parse (program) {
-    debug('program', program)
+const isThenable = (value) => (
+  value != null && typeof value.then === 'function'
+)
 
-    const awaits = []
-    const resolved = {}
+const isAwaitPromise = Symbol('sendscript-await')
+const undefinedSentinel = Symbol('sendscript-undefined')
 
-    JSON.parse(program, (key, value) => {
-      if (!Array.isArray(value)) return value
+const isPlainObject = (value) => {
+  if (!value || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
 
-      const [operator, ...rest] = value
+const markAwait = (promise) => {
+  promise[isAwaitPromise] = true
+  return promise
+}
 
-      if (operator === 'await') {
-        const [program, awaitId] = rest
-
-        awaits.push(((program, awaitId) => async () => {
-          resolved[awaitId] = await JSON.parse(
-            JSON.stringify(program),
-            reviver
-          )
-        })(program, awaitId))
-      }
+const isExplicitAwait = (value) => (
+  isThenable(value) && value[isAwaitPromise] === true
+)
 
-      return value
+// Recursively resolve awaited values in a parsed tree
+const resolveAwaitedValues = (value) => {
+  if (value === undefinedSentinel) return undefined
+
+  if (isThenable(value)) {
+    return isExplicitAwait(value)
+      ? markAwait(value.then(resolveAwaitedValues))
+      : value
+  }
+
+  if (Array.isArray(value)) {
+    let hasAwait = false
+    const result = value.map((item) => {
+      const resolved = resolveAwaitedValues(item)
+      if (isExplicitAwait(resolved)) hasAwait = true
+      return resolved
     })
 
-    const spy = fn => (...args) => {
-      const value = fn(...args)
-      debug(args, ' => ', value)
-      return value
+    if (!hasAwait) return result
+
+    const awaited = result.map((item, index) =>
+      isExplicitAwait(item)
+        ? Promise.resolve(item).then((resolved) => {
+          result[index] = resolved
+          return resolved
+        })
+        : item
+    )
+
+    return markAwait(Promise.all(awaited).then(() => result))
+  }
+
+  if (isPlainObject(value)) {
+    const result = {}
+    const promises = []
+
+    for (const key of Object.keys(value)) {
+      const resolved = resolveAwaitedValues(value[key])
+      if (isExplicitAwait(resolved)) {
+        promises.push(
+          Promise.resolve(resolved).then((resolvedValue) => {
+            result[key] = resolvedValue
+          })
+        )
+      } else {
+        result[key] = resolved
+      }
     }
 
+    if (!promises.length) return result
+    return markAwait(Promise.all(promises).then(() => result))
+  }
+
+  return value
+}
+
+const spy = (fn) => (...args) => {
+  const value = fn(...args)
+  debug(args, ' => ', value)
+  return value
+}
+
+const defaultLeafDeserializer = (text) => JSON.parse(text)
+
+export default (schemaArg, env, deserialize = defaultLeafDeserializer) => {
+  const schema = flattenSchema(schemaArg)
+
+  return function parse (program) {
+    debug('program', program)
+
     const reviver = spy((key, value) => {
-      if (isNil(value)) return value
+      if (value === null) return value
 
       if (!Array.isArray(value)) {
         return value
@@ -45,48 +127,64 @@ export default (env) =>
 
       const [operator, ...rest] = value
 
-      if (operator === 'await') {
-        const [, awaitId] = rest
-        debug('read awaits', resolved[awaitId], awaitId)
+      if (operator === 'leaf') {
+        const leafValue = deserialize(rest[0])
+        return leafValue === undefined ? undefinedSentinel : leafValue
+      }
 
-        return resolved[awaitId]
+      if (operator === 'await') {
+        const [program] = rest
+        return markAwait(Promise.resolve(program))
       }
 
       if (Array.isArray(operator) && operator[0] === 'quote') {
         const [, quoted] = operator
-
         return [quoted, ...rest]
       }
 
       if (operator === 'call') {
         const [fn, args] = rest
-
-        return fn(...args)
+        const resolvedFn = isExplicitAwait(fn) ? Promise.resolve(fn) : fn
+        const resolvedArgs = resolveAwaitedValues(args)
+
+        if (isExplicitAwait(resolvedFn) || isExplicitAwait(resolvedArgs)) {
+          const promiseFn = isExplicitAwait(resolvedFn)
+            ? Promise.resolve(resolvedFn)
+            : resolvedFn
+          const promiseArgs = isExplicitAwait(resolvedArgs)
+            ? Promise.resolve(resolvedArgs)
+            : resolvedArgs
+
+          return Promise.all([promiseFn, promiseArgs])
+            .then(([resolvedFnValue, resolvedArgsValue]) => resolvedFnValue(...resolvedArgsValue))
+        }
+
+        return fn(...resolvedArgs)
       }
 
       if (operator === 'ref') {
-        const [name] = rest
-
-        if (Object.hasOwn(env, name)) return env[name]
-
-        throw new SendScriptReferenceError({ key, value })
+        const path = rest // e.g., ["math","add"]
+        let current = env
+        let schemaCurrent = schema
+
+        for (const segment of path) {
+          if (schemaCurrent && Object.hasOwn(schemaCurrent, segment)) {
+            current = current[segment]
+            schemaCurrent = schemaCurrent[segment]
+          } else {
+            throw new SendScriptReferenceError({ key, value })
+          }
+        }
+
+        return current
       }
 
       return value
     })
 
-    if (awaits.length) {
-      return sequential(awaits).then(() => {
-        return JSON.parse(program, reviver)
-      })
-    }
+    const parsed = JSON.parse(program, reviver)
+    const result = resolveAwaitedValues(parsed)
 
-    return JSON.parse(program, reviver)
+    return result
   }
-
-function sequential (promises) {
-  return promises.reduce(
-    (acc, curr) => acc.then(results => curr().then(res => [...results, res])),
-    Promise.resolve([])
-  )
 }