@arcships/rutis 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @arcships/rutis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write [rutis](https://github.com/arcships/rutis) plugins in TypeScript or JavaScript.
+
+```ts
+import { definePlugin } from '@arcships/rutis'
+
+export default definePlugin({
+  inject: ['llm'],                              // services it uses
+  provides: { weather: { today: 'async' } },    // services it provides
+  config: { type: 'object', properties: { city: { type: 'string' } } },
+  apply(ctx, config) {
+    ctx.provide('weather', new Weather(ctx.use('llm'), config.city))
+    return () => {}                             // cleanup
+  },
+})
+```
+
+Test it without a host:
+
+```ts
+import { load } from '@arcships/rutis/testing'
+
+const t = await load(plugin, { config: { city: 'Oslo' }, services: { llm: { ask: async () => 'sunny' } } })
+assert.equal(await t.service('weather').today(), 'sunny in Oslo')
+await t.unload()
+```
+
+This package has no dependencies; the host installs the runtime that runs the plugin (`@arcships/rutis-runtime`). Start a project with `npx @arcships/rutis-host new <name> --lang node`.
+
+Guide (Chinese): [docs/guide/typescript-plugin.md](https://github.com/arcships/rutis/blob/main/docs/guide/typescript-plugin.md).

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@arcships/rutis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "Write rutis plugins in JavaScript or TypeScript: definePlugin, types and a test kit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcships/rutis.git",
+    "directory": "node/rutis"
+  },
+  "homepage": "https://github.com/arcships/rutis/tree/main/docs/guide#readme",
+  "keywords": ["rutis", "plugin", "rutis-plugin"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./testing": {
+      "types": "./src/testing.d.ts",
+      "default": "./src/testing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,32 @@
+export type MethodKind = 'sync' | 'async'
+
+export interface Context {
+  /** The service `name`, which the plugin declares in `inject`: the object itself when a plugin in the same process provides it, else a proxy whose methods are sync or async as declared. */
+  use<T = any>(name: string): T
+  /** Provide `value` as the service `name` until the plugin unloads, or until the returned function is called. */
+  provide(name: string, value: unknown): () => unknown
+  /** Run `cleanup` when the plugin unloads. */
+  effect(cleanup: () => unknown): void
+}
+
+export interface PluginSpec<C = any> {
+  name?: string
+  /** Services the plugin uses: rutis starts it once they are all available, and stops it when one goes. */
+  inject?: string[]
+  /** Services it provides to rutis, with each method's kind. */
+  provides?: Record<string, Record<string, MethodKind>>
+  /** The JSON Schema of its config. */
+  config?: object
+  apply(ctx: Context, config: C): void | (() => unknown) | Promise<void | (() => unknown)>
+}
+
+export interface Plugin<C = any> extends Readonly<Required<Pick<PluginSpec<C>, 'inject' | 'provides'>>>, Readonly<PluginSpec<C>> {
+  /** The plugin API it was written against. */
+  readonly api: number
+}
+
+/** The plugin API this SDK writes plugins against. */
+export declare const PLUGIN_API: number
+export declare const PLUGIN: unique symbol
+export declare function definePlugin<C = any>(spec: PluginSpec<C>): Plugin<C>
+export declare function isPlugin(value: unknown): value is Plugin

package/src/index.mjs

@@ -0,0 +1,37 @@
+// Write a rutis plugin in JavaScript or TypeScript. A plugin declares the
+// services it uses (`inject`) and provides (`provides`), and `apply(ctx,
+// config)` uses and provides them through `ctx`; rutis decides when it
+// starts, stops and restarts. The runtime that runs it is installed by the
+// host (`@arcships/rutis-runtime`), not by the plugin.
+//
+//   export default definePlugin({
+//     inject: ['llm'],
+//     provides: { weather: { today: 'async' } },
+//     config: { type: 'object', properties: { city: { type: 'string' } } },
+//     apply(ctx, config) {
+//       ctx.provide('weather', new Weather(ctx.use('llm'), config.city))
+//       return () => {}
+//     },
+//   })
+
+// The plugin API this SDK writes plugins against. A runtime refuses a plugin
+// that needs a newer one, naming both.
+export const PLUGIN_API = 1
+
+// Marks what definePlugin returns, across copies of this package.
+export const PLUGIN = Symbol.for('rutis.leaf-plugin')
+
+export function definePlugin(spec) {
+  if (typeof spec?.apply !== 'function') throw new TypeError('a plugin needs apply(ctx, config)')
+  const inject = spec.inject ?? []
+  if (!Array.isArray(inject) || inject.some(name => typeof name !== 'string')) throw new TypeError('inject must be a list of service names')
+  for (const [name, methods] of Object.entries(spec.provides ?? {})) {
+    for (const [method, kind] of Object.entries(methods ?? {})) {
+      if (kind !== 'sync' && kind !== 'async') throw new TypeError(`${name}.${method}: kind must be 'sync' or 'async'`)
+    }
+  }
+  return Object.freeze({ ...spec, inject, provides: spec.provides ?? {}, api: PLUGIN_API, [PLUGIN]: true })
+}
+
+// Whether `value` is a plugin definePlugin made.
+export const isPlugin = value => value?.[PLUGIN] === true

package/src/testing.d.ts

@@ -0,0 +1,23 @@
+import type { Plugin } from './index.js'
+
+export declare class PluginTestError extends Error {}
+
+export interface Loaded {
+  /** The service `name` the plugin provides, as rutis sees it: its declared methods only. */
+  service<T = any>(name: string): T
+  /** The names of the services the plugin provides now. */
+  provided(): string[]
+  /** Run the cleanups, latest first; the plugin's services are withdrawn. */
+  unload(): Promise<void>
+}
+
+export interface LoadOptions {
+  config?: unknown
+  /** The services the plugin injects, by name. */
+  services?: Record<string, unknown>
+  /** Values cross as between processes (default true). */
+  strict?: boolean
+}
+
+/** Load `plugin` (or a module whose default export it is) without a host. */
+export declare function load(plugin: Plugin | { default: Plugin }, options?: LoadOptions): Promise<Loaded>

package/src/testing.mjs

@@ -0,0 +1,154 @@
+// Test a plugin without a host: give it the services it injects, call the
+// services it provides, unload it.
+//
+//   const t = await load(plugin, { config: { city: 'Oslo' }, services: { llm } })
+//   assert.equal(await t.service('weather').today(), 'sunny in Oslo')
+//   await t.unload()
+//
+// It checks what a host would: the plugin uses only the services it declares
+// in `inject`, provides what it declares in `provides` with every declared
+// method, and runs its cleanups on unload. With `strict` (the default),
+// values cross between the plugin and the test as they would between
+// processes: data is copied, functions and objects with behaviour pass by
+// reference, sync methods return values and async ones promises; what
+// works only in one process fails here too.
+
+import { PLUGIN_API, isPlugin } from './index.mjs'
+
+export class PluginTestError extends Error {
+  name = 'PluginTestError'
+}
+
+const builtins = [Date, RegExp, Map, Set, WeakMap, WeakSet, ArrayBuffer, DataView, Error, Promise]
+
+// Objects with behaviour cross by reference: class instances and objects
+// with methods. Everything else is data.
+function hasBehaviour(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value) || ArrayBuffer.isView(value)) return false
+  if (builtins.some(type => value instanceof type)) return false
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype !== Object.prototype && prototype !== null) return true
+  return Object.values(value).some(item => typeof item === 'function')
+}
+
+// `value` as the other process sees it.
+function cross(value, where, seen = new Set()) {
+  if (value === undefined || value === null) return value
+  if (typeof value === 'symbol' || typeof value === 'bigint') {
+    throw new PluginTestError(`${where}: a ${typeof value} cannot cross between processes`)
+  }
+  if (typeof value === 'function') return (...args) => crossResult(value(...args.map((arg, i) => cross(arg, `${where} argument ${i}`))), where)
+  if (value instanceof Promise) return value.then(result => cross(result, where))
+  if (typeof value !== 'object') return value
+  if (hasBehaviour(value)) return reference(value, where)
+  if (value instanceof Error) return Object.assign(new Error(value.message), { name: value.name })
+  if (seen.has(value)) throw new PluginTestError(`${where}: cyclic data cannot cross between processes`)
+  seen.add(value)
+  try {
+    if (Array.isArray(value)) return value.map((item, i) => cross(item, `${where}[${i}]`, seen))
+    if (builtins.some(type => value instanceof type) || ArrayBuffer.isView(value)) return JSON.parse(JSON.stringify(value))
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cross(item, `${where}.${key}`, seen)]))
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function crossResult(result, where) {
+  return result instanceof Promise ? result.then(value => cross(value, where)) : cross(result, where)
+}
+
+// An object with behaviour, used from the other process: its methods are
+// called by reference.
+function reference(target, where) {
+  return new Proxy(target, {
+    get(object, property) {
+      const value = Reflect.get(object, property, object)
+      return typeof value === 'function' ? cross(value.bind(object), `${where}.${String(property)}`) : cross(value, `${where}.${String(property)}`)
+    },
+  })
+}
+
+// A service seen through its declared shape: only declared methods, sync
+// ones returning values, async ones promises.
+function shaped(name, object, shape, strict) {
+  const service = {}
+  for (const [method, kind] of Object.entries(shape)) {
+    service[method] = (...args) => {
+      const where = `${name}.${method}`
+      const crossed = strict ? args.map((arg, i) => cross(arg, `${where} argument ${i}`)) : args
+      const result = object[method](...crossed)
+      if (kind === 'sync') {
+        if (result instanceof Promise) throw new PluginTestError(`${where} is declared sync but returned a promise: declare it 'async'`)
+        return strict ? cross(result, where) : result
+      }
+      return Promise.resolve(result).then(value => (strict ? cross(value, where) : value))
+    }
+  }
+  return service
+}
+
+/**
+ * Load `plugin` (what definePlugin returns, or a module whose default export
+ * it is) with `config` and the services in `services`.
+ */
+export async function load(plugin, { config = {}, services = {}, strict = true } = {}) {
+  plugin = isPlugin(plugin) ? plugin : plugin?.default
+  if (!isPlugin(plugin)) throw new PluginTestError('load needs a plugin made with definePlugin')
+  if (plugin.api > PLUGIN_API) {
+    throw new PluginTestError(`the plugin needs plugin API ${plugin.api}; this SDK supports ${PLUGIN_API}`)
+  }
+  for (const name of plugin.inject) {
+    if (!(name in services)) throw new PluginTestError(`the plugin injects ${name}: give the test a service ${name}`)
+  }
+  const provided = new Map()
+  const cleanups = []
+  let unloaded = false
+  const ctx = {
+    use(name) {
+      if (!plugin.inject.includes(name)) throw new PluginTestError(`the plugin uses ${name} without declaring it in inject`)
+      return strict ? cross(services[name], `service ${name}`) : services[name]
+    },
+    provide(name, value) {
+      const shape = plugin.provides[name]
+      if (shape) {
+        for (const method of Object.keys(shape)) {
+          if (typeof value?.[method] !== 'function') throw new PluginTestError(`${name} is declared with ${method} in provides, but the service has no such method`)
+        }
+      }
+      const entry = { value }
+      provided.set(name, entry)
+      return () => {
+        if (provided.get(name) === entry) provided.delete(name)
+      }
+    },
+    effect(cleanup) {
+      if (typeof cleanup !== 'function') throw new PluginTestError('effect needs a cleanup function')
+      cleanups.push(cleanup)
+    },
+  }
+  const returned = await plugin.apply(ctx, strict ? cross(config, 'config') : config)
+  if (returned !== undefined && returned !== null) {
+    if (typeof returned !== 'function') throw new PluginTestError('apply must return a cleanup function or nothing')
+    cleanups.push(returned)
+  }
+  return {
+    /** The service `name` the plugin provides, as rutis sees it: its declared methods only. */
+    service(name) {
+      if (unloaded) throw new PluginTestError('the plugin is unloaded')
+      const shape = plugin.provides[name]
+      if (!shape) throw new PluginTestError(`${name} is not declared in provides, so rutis cannot use it`)
+      const entry = provided.get(name)
+      if (!entry) throw new PluginTestError(`the plugin does not provide ${name} (now)`)
+      return shaped(name, entry.value, shape, strict)
+    },
+    /** The names of the services the plugin provides now. */
+    provided: () => [...provided.keys()],
+    /** Run the cleanups, latest first; the plugin's services are withdrawn. */
+    async unload() {
+      if (unloaded) return
+      unloaded = true
+      for (const cleanup of cleanups.reverse()) await cleanup()
+      provided.clear()
+    },
+  }
+}