@toa.io/definitions 1.0.0-alpha.288 → 1.0.0-alpha.293

package/source/bindings.amqp/sources.ts

@@ -1,39 +0,0 @@
-import { createVariables, type Request } from '@toa.io/pointer'
-import { type Manifest } from '@toa.io/norm'
-import { type Dependency } from '@toa.io/operations'
-import { type Instance } from './instance.js'
-import { type Annotation } from './annotation.js'
-
-export function createDependency(sources: Sources, instances: Instance[]): Dependency {
-  const requests = []
-
-  for (const instance of instances) {
-    const request = createRequest(instance)
-
-    if (request !== null) requests.push(request)
-  }
-
-  const variables = createVariables(ID, sources, requests)
-
-  return { variables }
-}
-
-function createRequest(instance: Instance): Request | null {
-  const group = instance.locator.label
-  const selectors = createSelectors(instance.component)
-
-  if (selectors === null) return null
-  else return { group, selectors }
-}
-
-function createSelectors(component: Manifest): string[] | null {
-  if (component.receivers === undefined) return null
-
-  const sources = Object.values(component.receivers).map((receiver) => receiver.source)
-
-  return sources.filter((source) => source !== undefined) as string[]
-}
-
-export const ID = 'amqp-sources'
-
-type Sources = Annotation['sources']

package/source/bindings.loop/index.ts

@@ -1,3 +0,0 @@
-import type { bindings } from '@toa.io/core/types'
-
-export const properties: bindings.Properties = { async: false, local: true }

package/source/bridges.bash/const.ts

@@ -1,2 +0,0 @@
-export const DIR = 'operations'
-export const EXT = '.sh'

package/source/bridges.bash/define.ts

@@ -1,38 +0,0 @@
-import * as fs from 'node:fs/promises'
-import { join, extname } from 'node:path'
-import { DIR, EXT } from './const.js'
-import type { component } from '@toa.io/norm'
-
-export async function operations(root: string): Promise<component.Operations> {
-  const path = join(root, DIR)
-  const names = await list(path)
-
-  const promises = names.map(async (name) => operation(root, name))
-
-  const operations = await Promise.all(promises)
-
-  return operations.reduce<component.Operations>((acc, operation, index) => {
-    acc[names[index]] = operation
-
-    return acc
-  }, {})
-}
-
-export async function operation(
-  root: string,
-  name: string
-): Promise<component.Operation> {
-  const path = join(root, DIR, name + EXT)
-
-  await fs.access(path, fs.constants.F_OK)
-
-  return { type: 'computation' }
-}
-
-async function list(path: string): Promise<string[]> {
-  const files = await fs.readdir(path)
-
-  return files
-    .filter((file) => extname(file) === EXT)
-    .map((file) => file.slice(0, -EXT.length))
-}

package/source/bridges.bash/index.ts

@@ -1,2 +0,0 @@
-export * as define from './define.js'
-export { DIR, EXT } from './const.js'

package/source/bridges.node/define.ts

@@ -1,69 +0,0 @@
-import { readFile } from 'node:fs/promises'
-import { sources } from './sources.js'
-import { exports, type Exports } from './exports.js'
-import { algorithm, type Definition } from './operations.js'
-
-/**
- * What a component's modules declare, read from their source and never by importing them: a
- * deploy reads a component whose dependencies are not installed, and a booting process reads
- * the same, so the two cannot disagree.
- */
-export async function operations(root: string): Promise<Record<string, Definition>> {
-  const algorithms: Record<string, Definition> = {}
-
-  for (const [name, exported, path] of await read(root, 'operations')) {
-    const definition = algorithm(exported, path)
-
-    if (definition !== null) algorithms[name] = definition
-  }
-
-  return algorithms
-}
-
-export async function events(root: string): Promise<Record<string, Event>> {
-  const events: Record<string, Event> = {}
-
-  for (const [name, exported] of await read(root, 'events'))
-    events[name] = { conditioned: exported.has('condition'), subjective: exported.has('payload') }
-
-  return events
-}
-
-export async function receivers(root: string): Promise<Record<string, Receiver>> {
-  const receivers: Record<string, Receiver> = {}
-
-  for (const [name, exported] of await read(root, 'receivers'))
-    receivers[name] = { conditioned: exported.has('condition'), adaptive: exported.has('request') }
-
-  return receivers
-}
-
-export async function guards(root: string): Promise<Record<string, object>> {
-  const guards: Record<string, object> = {}
-
-  for (const [name, exported] of await read(root, 'guards')) if (exported.has('guard')) guards[name] = {}
-
-  return guards
-}
-
-async function read(root: string, directory: string): Promise<Array<[string, Exports, string]>> {
-  const modules = await sources(root, directory)
-
-  return Promise.all(
-    [...modules].map(async ([name, path]): Promise<[string, Exports, string]> => [
-      name,
-      exports(path, await readFile(path, 'utf8')),
-      path
-    ])
-  )
-}
-
-export interface Event {
-  conditioned: boolean
-  subjective: boolean
-}
-
-export interface Receiver {
-  conditioned: boolean
-  adaptive: boolean
-}

package/source/bridges.node/exports.ts

@@ -1,175 +0,0 @@
-import { parseSync } from 'oxc-parser'
-
-/**
- * What a module exports, read from its source: the name, and what the value is declared as.
- * Nothing is imported, so what a module depends on need not be installed to read it.
- */
-export function exports(path: string, text: string): Exports {
-  const { program, errors } = parseSync(path, text)
-
-  if (errors.length > 0) throw new Error(`${path}: ${errors[0].message}`)
-
-  const locals = declarations(program.body)
-  const exported: Exports = new Map()
-
-  for (const node of program.body) {
-    if (node.type === 'ExportNamedDeclaration') named(node, locals, exported)
-    else if (node.type === 'ExportDefaultDeclaration')
-      exported.set('default', binding(node.declaration, locals))
-    else if (node.type === 'ExpressionStatement') assigned(node.expression, locals, exported)
-  }
-
-  return exported
-}
-
-export type Exports = Map<string, Binding>
-
-export interface Binding {
-  /** what the value is declared as, or `other` where it is computed rather than written */
-  kind: 'function' | 'class' | 'other'
-  /** the name a function or class is declared with, which a default export is known by */
-  declared?: string
-  /** the parameters' names, `undefined` for one that is not a plain identifier */
-  params?: Array<string | undefined>
-  /** a class's methods with their parameters */
-  methods?: Record<string, Array<string | undefined>>
-}
-
-function named(node: any, locals: Locals, exported: Exports): void {
-  if (node.exportKind === 'type') return
-
-  const declaration = node.declaration
-
-  if (declaration !== null && declaration !== undefined)
-    for (const [name, bound] of declared(declaration)) exported.set(name, bound)
-
-  for (const specifier of node.specifiers ?? []) {
-    if (specifier.exportKind === 'type') return
-
-    exported.set(name(specifier.exported), binding(specifier.local, locals))
-  }
-}
-
-/** `module.exports = { … }`, `module.exports.x = …` and `exports.x = …` */
-function assigned(expression: any, locals: Locals, exported: Exports): void {
-  if (expression.type !== 'AssignmentExpression' || expression.operator !== '=') return
-
-  const target = expression.left
-
-  if (target.type !== 'MemberExpression') return
-
-  if (isModuleExports(target)) {
-    if (expression.right.type === 'ObjectExpression')
-      properties(expression.right, locals, exported)
-
-    return
-  }
-
-  const object = target.object
-
-  if (isModuleExports(object) || (object.type === 'Identifier' && object.name === 'exports'))
-    exported.set(name(target.property), binding(expression.right, locals))
-}
-
-/** `{ computation, condition: () => … }` — each property is an export. */
-function properties(object: any, locals: Locals, exported: Exports): void {
-  for (const property of object.properties) {
-    if (property.type !== 'Property') continue
-
-    exported.set(name(property.key), binding(property.value, locals))
-  }
-}
-
-function isModuleExports(node: any): boolean {
-  return (
-    node.type === 'MemberExpression' &&
-    node.object.type === 'Identifier' &&
-    node.object.name === 'module' &&
-    name(node.property) === 'exports'
-  )
-}
-
-/** Every top-level declaration, which a specifier or a shorthand property refers to by name. */
-function declarations(body: any[]): Locals {
-  const locals: Locals = new Map()
-
-  for (const node of body) {
-    const declaration =
-      node.type === 'ExportNamedDeclaration' ? node.declaration : node
-
-    if (declaration === null || declaration === undefined) continue
-
-    for (const [name, bound] of declared(declaration)) locals.set(name, bound)
-  }
-
-  return locals
-}
-
-function declared(node: any): Array<[string, Binding]> {
-  switch (node.type) {
-    case 'FunctionDeclaration':
-    case 'ClassDeclaration':
-      return node.id === null ? [] : [[node.id.name, binding(node)]]
-    case 'VariableDeclaration':
-      return node.declarations
-        .filter((declarator: any) => declarator.id.type === 'Identifier')
-        .map((declarator: any) => [
-          declarator.id.name,
-          declarator.init === null ? OTHER : binding(declarator.init)
-        ])
-    default:
-      return []
-  }
-}
-
-function binding(node: any, locals?: Locals): Binding {
-  switch (node.type) {
-    case 'FunctionDeclaration':
-    case 'FunctionExpression':
-    case 'ArrowFunctionExpression':
-      return { kind: 'function', declared: node.id?.name, params: parameters(node.params) }
-    case 'ClassDeclaration':
-    case 'ClassExpression':
-      return { kind: 'class', declared: node.id?.name, methods: methods(node.body.body) }
-    case 'Identifier':
-      return locals?.get(node.name) ?? OTHER
-    default:
-      return OTHER
-  }
-}
-
-function methods(body: any[]): Record<string, Array<string | undefined>> {
-  const methods: Record<string, Array<string | undefined>> = {}
-
-  for (const member of body) {
-    if (member.key === undefined || member.key.type === 'PrivateIdentifier') continue
-
-    if (member.type === 'MethodDefinition') methods[name(member.key)] = parameters(member.value.params)
-    else if (
-      member.type === 'PropertyDefinition' &&
-      member.value !== null &&
-      (member.value.type === 'ArrowFunctionExpression' ||
-        member.value.type === 'FunctionExpression')
-    )
-      methods[name(member.key)] = parameters(member.value.params)
-  }
-
-  return methods
-}
-
-/** A name is what is read: a pattern, a rest or a `this` annotation is not a name. */
-function parameters(params: any[]): Array<string | undefined> {
-  return params.map((param) => {
-    const pattern = param.type === 'AssignmentPattern' ? param.left : param
-
-    return pattern.type === 'Identifier' ? pattern.name : undefined
-  })
-}
-
-function name(key: any): string {
-  return key.type === 'Identifier' ? key.name : String(key.value)
-}
-
-type Locals = Map<string, Binding>
-
-const OTHER: Binding = { kind: 'other' }

package/source/bridges.node/index.ts

@@ -1,6 +0,0 @@
-export * as define from './define.js'
-export { exports } from './exports.js'
-export { algorithm, TYPES } from './operations.js'
-
-export type { Binding, Exports } from './exports.js'
-export type { Definition } from './operations.js'

package/source/bridges.node/operations.ts

@@ -1,127 +0,0 @@
-import type { Binding, Exports } from './exports.js'
-
-/**
- * What an algorithm module declares, by the conventions the bridge reads a module by: the
- * exported name is the type, the second parameter's name is the scope. `null` where the module
- * exports no algorithm.
- */
-export function algorithm(exported: Exports, path: string): Definition | null {
-  const entry = find(exported, path)
-
-  if (entry === null) return null
-
-  const [name, bound] = entry
-
-  if (FACTORY.test(name)) return factory(name, bound, path)
-  if (CLASSES.has(name)) return klass(name, bound, path)
-  if (TYPES.has(name)) return func(name, bound)
-
-  throw new Error(`${path}: exported '${name}' does not match conventions`)
-}
-
-export interface Definition {
-  type: string
-  scope?: string
-  input?: null
-}
-
-/**
- * A module names its algorithm by exporting it, and it exports one. What a value is cannot
- * always be read from its source — `export const computation = wrap(fn)` — so a name written the
- * way an algorithm's is counts, whatever it is bound to.
- */
-function find(exported: Exports, path: string): [string, Binding] | null {
-  const candidates = [...exported].filter(
-    ([name, bound]) => name !== '__esModule' && (bound.kind !== 'other' || conventional(name))
-  )
-
-  if (candidates.length === 0) return null
-
-  if (candidates.length === 1) return resolve(candidates[0])
-
-  const named = candidates.filter(([name]) => name !== 'default')
-
-  if (named.length === 1) return named[0]
-
-  throw new Error(
-    `${path}: a module must export one algorithm, and this one exports ` +
-      named.map(([name]) => `'${name}'`).join(', ')
-  )
-}
-
-/** `export default function transition` says its name in the function itself. */
-function resolve([name, bound]: [string, Binding]): [string, Binding] {
-  return name === 'default' ? [bound.declared ?? '', bound] : [name, bound]
-}
-
-function conventional(name: string): boolean {
-  return TYPES.has(name) || CLASSES.has(name) || FACTORY.test(name)
-}
-
-function func(type: string, bound: Binding): Definition {
-  const definition: Definition = { type }
-
-  // computed rather than written: the scope is the manifest's to declare
-  if (bound.kind === 'other') return definition
-
-  if (bound.kind !== 'function' || bound.params === undefined)
-    throw new Error(`Exported '${type}' does not match conventions`)
-
-  return signature(definition, bound.params)
-}
-
-function klass(name: string, bound: Binding, path: string): Definition {
-  if (bound.kind !== 'class') throw new Error(`${path}: '${name}' does not match conventions`)
-
-  const params = bound.methods?.execute
-
-  if (params === undefined) throw new Error(`${path}: Method 'execute' not found in '${name}'`)
-
-  return signature({ type: name.toLowerCase() }, params)
-}
-
-function factory(name: string, bound: Binding, path: string): Definition {
-  if (bound.kind !== 'class') throw new Error(`${path}: '${name}' does not match conventions`)
-
-  const match = name.match(FACTORY)!
-  const definition: Definition = { type: match.groups!.type.toLowerCase() }
-  const scope = match.groups!.scope?.toLowerCase()
-
-  if (scope !== undefined) definition.scope = scope
-
-  return definition
-}
-
-function signature(definition: Definition, params: Array<string | undefined>): Definition {
-  definition.scope = params.length > 1 ? scope(params[1]) : 'none'
-
-  if (params.length === 0) definition.input = null
-
-  return definition
-}
-
-function scope(name: string | undefined): string | undefined {
-  if (name === undefined) return undefined
-  if (SCOPES.has(name)) return name
-  if (name === 'context') return 'none'
-
-  return undefined
-}
-
-export const TYPES: ReadonlySet<string> = new Set([
-  'transition',
-  'observation',
-  'assignment',
-  'computation',
-  'effect',
-  'unmanaged'
-])
-
-const SCOPES: ReadonlySet<string> = new Set(['object', 'objects', 'changeset', 'stream'])
-
-const CLASSES: ReadonlySet<string> = new Set(
-  [...TYPES].map((type) => type[0].toUpperCase() + type.slice(1))
-)
-
-const FACTORY =
-  /^(?<scope>Objects?|Changeset)?(?<type>Transition|Observation|Assignment|Computation|Effect)Factory$/

package/source/bridges.node/sources.ts

@@ -1,44 +0,0 @@
-import { readdir } from 'node:fs/promises'
-import { basename, extname, join } from 'node:path'
-
-/**
- * A component's modules by name, whatever extension each was written with.
- *
- * Two files that resolve to one name are a conflict rather than a race: which of them a scan
- * reached first is not something a component may depend on.
- */
-export async function sources(root: string, directory: string): Promise<Map<string, string>> {
-  const path = join(root, directory)
-  const files = (await list(path)).filter((file) => EXTENSIONS.has(extname(file))).sort()
-  const modules = new Map<string, string>()
-
-  // sorted, so the two files a conflict names are the same two on every machine
-  for (const file of files) {
-    const name = basename(file, extname(file))
-    const found = modules.get(name)
-
-    if (found !== undefined)
-      throw new Error(
-        `Component at '${root}' has more than one ${directory}/${name}: ` +
-          `${basename(found)} and ${file}`
-      )
-
-    modules.set(name, join(path, file))
-  }
-
-  return modules
-}
-
-async function list(path: string): Promise<string[]> {
-  try {
-    const entries = await readdir(path, { withFileTypes: true })
-
-    return entries.filter((entry) => entry.isFile()).map((entry) => entry.name)
-  } catch (error: any) {
-    if (error.code === 'ENOENT') return []
-
-    throw error
-  }
-}
-
-const EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts'])

package/source/definition.ts

@@ -1,38 +0,0 @@
-/**
- * A first-party package's definition, by the reference a manifest or a context names it by.
- * `undefined` for a package this one does not define, which norm then reads on its own.
- */
-export async function definition(reference: string): Promise<object | undefined> {
-  if (!reference.startsWith(SCOPE)) return undefined
-
-  const suffix = reference.slice(SCOPE.length)
-
-  if (!DEFINED.has(suffix)) return undefined
-
-  cache[suffix] ??= import(`./${suffix}/index.js`)
-
-  return cache[suffix]
-}
-
-const cache: Record<string, Promise<object>> = {}
-
-const SCOPE = '@toa.io/'
-
-/** Every package defined here, by its directory, which is its name within the scope. */
-export const DEFINED: ReadonlySet<string> = new Set([
-  'bindings.amqp',
-  'bindings.loop',
-  'bridges.bash',
-  'bridges.node',
-  'extensions.cadence',
-  'extensions.configuration',
-  'extensions.exposition',
-  'extensions.fetch',
-  'extensions.introspection',
-  'extensions.realtime',
-  'extensions.stash',
-  'extensions.state',
-  'extensions.storages',
-  'extensions.telemetry',
-  'storages.mongodb'
-])

package/source/digest/generate.ts

@@ -1,77 +0,0 @@
-import { createRequire } from 'node:module'
-import { dirname, join, relative, resolve, sep } from 'node:path'
-import { mkdirSync, readdirSync, writeFileSync } from 'node:fs'
-import type { Entry } from './read.js'
-
-/**
- * Writes the digest of the components each extension ships: their manifests as norm reads
- * them, with every path that reaches into a package replaced by that package's name — so the
- * digest reads the same wherever this package is installed.
- *
- * Runs after the workspace transpiled, from the workspace, where every extension resolves.
- */
-const require = createRequire(import.meta.url)
-
-// norm types its manifests, not its functions
-const { component } = (await import('@toa.io/norm')) as unknown as {
-  component: (path: string) => Promise<object>
-}
-
-const DIGESTED = [
-  'extensions.cadence',
-  'extensions.configuration',
-  'extensions.exposition',
-  'extensions.introspection',
-  'extensions.realtime'
-]
-
-const OUT = resolve(import.meta.dirname, '../../digest')
-
-mkdirSync(OUT, { recursive: true })
-
-const packages = ['@toa.io/prototype', ...DIGESTED.map((suffix) => '@toa.io/' + suffix)]
-const roots = new Map(packages.map((name) => [root(name), name]))
-
-for (const suffix of DIGESTED) {
-  const directory = join(root('@toa.io/' + suffix), 'components')
-  const entries: Entry[] = []
-
-  for (const dirent of readdirSync(directory, { withFileTypes: true })) {
-    if (!dirent.isDirectory()) continue
-
-    const manifest = await component(join(directory, dirent.name))
-
-    entries.push({ label: dirent.name.replace('.', '-'), manifest: relativize(manifest) })
-  }
-
-  writeFileSync(join(OUT, suffix + '.json'), JSON.stringify(entries))
-}
-
-function root(name: string): string {
-  return dirname(require.resolve(name + '/package.json'))
-}
-
-/** Absolute paths into a package become `<name>/<inside>`; the locator norm rebuilds. */
-function relativize(value: unknown): any {
-  if (typeof value === 'string') return specifier(value)
-  if (Array.isArray(value)) return value.map(relativize)
-
-  if (value !== null && typeof value === 'object') {
-    const object: Record<string, unknown> = {}
-
-    for (const [key, item] of Object.entries(value))
-      if (key !== 'locator') object[key] = relativize(item)
-
-    return object
-  }
-
-  return value
-}
-
-function specifier(value: string): string {
-  for (const [directory, name] of roots)
-    if (value === directory || value.startsWith(directory + sep))
-      return [name, ...relative(directory, value).split(sep)].filter(Boolean).join('/')
-
-  return value
-}

package/source/digest/read.ts

@@ -1,39 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-
-/**
- * The components an extension ships, as the digest of their manifests generated when this
- * package was built. A deploy reads them from here, because the extension is not installed
- * beside it; a running service reads them from the extension, where their code is.
- */
-export function components(suffix: string, filter?: (label: string) => boolean): Components {
-  const manifests = digest(suffix).filter((manifest) => filter?.(manifest.label) ?? true)
-
-  return {
-    labels: manifests.map((manifest) => manifest.label),
-    manifests: manifests.map((manifest) => structuredClone(manifest.manifest))
-  }
-}
-
-function digest(suffix: string): Entry[] {
-  cache[suffix] ??= JSON.parse(readFileSync(resolve(ROOT, suffix + '.json'), 'utf8'))
-
-  return cache[suffix]
-}
-
-const cache: Record<string, Entry[]> = {}
-
-/** `transpiled/digest/read.js` → `digest/` */
-const ROOT = resolve(import.meta.dirname, '../../digest')
-
-export interface Components {
-  /** what a chart names each component's workload by: `identity-basic` */
-  labels: string[]
-  /** the manifests as norm reads them, with `path` as a package-relative specifier */
-  manifests: object[]
-}
-
-export interface Entry {
-  label: string
-  manifest: object
-}

package/source/extensions.cadence/components.ts

@@ -1,6 +0,0 @@
-import { components as digest, type Components } from '../digest/read.js'
-
-/** The components this extension ships, which run inside its own service. */
-export function components(): Components {
-  return digest('extensions.cadence')
-}