@xrkseek/harness 0.4.8 → 0.4.10

package/node_modules/@xrkseek/cordis/src/events.js

@@ -0,0 +1,199 @@
+import { defineProperty } from '@xrkseek/cosmokit';
+import { Context } from "./context.js";
+import { DisposableList, symbols } from "./utils.js";
+/**
+ * Return whether an event result should stop a bail-style dispatch.
+ *
+ * @param value — a listener's return value.
+ * @returns `true` unless `value` is `null`, `false`, or `undefined`.
+ */
+export function isBailed(value) {
+    return value !== null && value !== false && value !== undefined;
+}
+/**
+ * Event bus installed as `ctx.events` and mixed into every context.
+ *
+ * The service supports concurrent, synchronous, serial, bail, and waterfall
+ * dispatch and automatically disposes listeners with their owning fiber.
+ */
+export class EventsService {
+    ctx;
+    _hooks = {};
+    constructor(ctx) {
+        this.ctx = ctx;
+        defineProperty(this, symbols.tracker, {
+            property: 'ctx',
+            noShadow: true,
+        });
+        this.on('internal/listener', function (name, listener, options) {
+            if (name === 'internal/update' && !options.global) {
+                const hooks = this.fiber._hooks['internal/update'] ??= new DisposableList();
+                const method = options.prepend ? 'unshift' : 'push';
+                return hooks[method](listener);
+            }
+        });
+        this.on('internal/update', function (config, noSave, next) {
+            const cbs = [...this._hooks['internal/update'] || []];
+            const _next = () => {
+                const cb = cbs.shift() ?? next;
+                return cb.call(this, config, noSave, _next);
+            };
+            return _next();
+        }, { global: true, prepend: true });
+    }
+    /**
+     * Resolve listeners for one dispatch and apply context filtering.
+     *
+     * @param type — the dispatch mode, reported on `internal/dispatch`.
+     * @param args — the raw dispatch arguments; consumed up to the event name.
+     * @returns the matching listener callbacks, bound to the dispatch `this`.
+     */
+    dispatch(type, args) {
+        const thisArg = typeof args[0] === 'object' || typeof args[0] === 'function' ? args.shift() : null;
+        const name = args.shift();
+        if (!name.startsWith('internal/')) {
+            this.emit('internal/dispatch', type, name, args, thisArg);
+        }
+        const filter = thisArg?.[Context.filter];
+        return (this._hooks[name] || [])
+            .filter(hook => hook.global || !filter || filter.call(thisArg, hook.ctx))
+            .map(hook => hook.callback.bind(thisArg));
+    }
+    /**
+     * Run listeners concurrently and wait for all of them.
+     *
+     * @param args — optional `this`, the event name, then listener arguments.
+     * @returns a promise resolving once every listener has settled.
+     */
+    async parallel(...args) {
+        const results = await Promise.allSettled(this.dispatch('emit', args).map(async (cb) => cb(...args)));
+        const errors = results.filter((result) => result.status === 'rejected');
+        if (errors.length)
+            throw new AggregateError(errors.map(error => error.reason));
+    }
+    /**
+     * Run listeners synchronously without waiting for returned promises.
+     *
+     * @param args — optional `this`, the event name, then listener arguments.
+     */
+    emit(...args) {
+        this.dispatch('emit', args).map(cb => cb(...args));
+    }
+    /**
+     * Run listeners in order, awaiting each, until one returns a bail value.
+     *
+     * @param args — optional `this`, the event name, then listener arguments.
+     * @returns the first bail value (see {@link isBailed}), if any.
+     */
+    async serial(...args) {
+        for (const cb of this.dispatch('serial', args)) {
+            const result = await cb(...args);
+            if (isBailed(result))
+                return result;
+        }
+    }
+    /**
+     * Run listeners synchronously until one returns a bail value.
+     *
+     * @param args — optional `this`, the event name, then listener arguments.
+     * @returns the first bail value (see {@link isBailed}), if any.
+     */
+    bail(...args) {
+        for (const cb of this.dispatch('bail', args)) {
+            const result = cb(...args);
+            if (isBailed(result))
+                return result;
+        }
+    }
+    /**
+     * Compose listeners around the final `next` callback.
+     *
+     * The last dispatch argument is treated as the innermost `next`. Listeners
+     * run outermost-first; a listener that does not call `next()` vetoes the
+     * rest of the chain, including the built-in behavior.
+     *
+     * @param args — optional `this`, the event name, listener arguments, then `next`.
+     * @returns the outermost listener's return value.
+     */
+    waterfall(...args) {
+        const cbs = this.dispatch('waterfall', args);
+        const inner = args.pop();
+        const next = () => {
+            const cb = cbs.shift() ?? inner;
+            return cb(...args);
+        };
+        args.push(next);
+        return next();
+    }
+    /**
+     * Store a listener record as an effect on the current fiber.
+     *
+     * @param label — effect label shown in fiber diagnostics.
+     * @param hooks — the listener list for one event.
+     * @param callback — the listener to store.
+     * @param options — placement and filtering options.
+     * @returns a disposer that unregisters the listener.
+     */
+    register(label, hooks, callback, options) {
+        const method = options.prepend ? 'unshift' : 'push';
+        return this.ctx.fiber.effect(() => {
+            hooks[method]({ ctx: this.ctx, callback, ...options });
+            return () => this.unregister(hooks, callback);
+        }, label);
+    }
+    /**
+     * Remove a stored listener record.
+     *
+     * @param hooks — the listener list for one event.
+     * @param callback — the listener to remove.
+     * @returns `true` if the listener was found and removed.
+     */
+    unregister(hooks, callback) {
+        const index = hooks.findIndex(hook => hook.callback === callback);
+        if (index >= 0) {
+            hooks.splice(index, 1);
+            return true;
+        }
+    }
+    /**
+     * Register an event listener owned by the current fiber.
+     *
+     * The listener is removed automatically when the fiber unloads. Throws
+     * `CordisError('INACTIVE_EFFECT')` if the fiber is already disposed.
+     *
+     * @param name — the event name to listen for.
+     * @param listener — called with the dispatch arguments.
+     * @param options — listener options; a boolean is shorthand for `prepend`.
+     * @returns a disposer removing the listener; `true` if it was still registered.
+     */
+    on(name, listener, options) {
+        if (typeof options !== 'object') {
+            options = { prepend: options };
+        }
+        // handle special events
+        this.ctx.fiber.assertActive();
+        listener = this.ctx.reflect.bind(listener);
+        const result = this.bail(this.ctx, 'internal/listener', name, listener, options);
+        if (result)
+            return result;
+        const hooks = this._hooks[name] ||= [];
+        const label = `ctx.on(${typeof name === 'string' ? JSON.stringify(name) : name.toString()})`;
+        return this.register(label, hooks, listener, options);
+    }
+    /**
+     * Register an event listener that disposes itself after the first call.
+     *
+     * @param name — the event name to listen for.
+     * @param listener — called at most once with the dispatch arguments.
+     * @param options — listener options; a boolean is shorthand for `prepend`.
+     * @returns a disposer removing the listener; `true` if it was still registered.
+     */
+    once(name, listener, options) {
+        const dispose = this.on(name, function (...args) {
+            dispose();
+            return listener.apply(this, args);
+        }, options);
+        return dispose;
+    }
+}
+//# sourceMappingURL=events.js.map

package/node_modules/@xrkseek/cordis/src/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["events.ts"],"names":[],"mappings":"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"}

package/node_modules/@xrkseek/cordis/src/events.ts

@@ -0,0 +1,352 @@
+import { defineProperty } from '@xrkseek/cosmokit'
+import type { Promisify } from '@xrkseek/cosmokit'
+import { Context } from './context.ts'
+import { Fiber, FiberState } from './fiber.ts'
+import { DisposableList, symbols } from './utils.ts'
+
+/**
+ * Return whether an event result should stop a bail-style dispatch.
+ *
+ * @param value — a listener's return value.
+ * @returns `true` unless `value` is `null`, `false`, or `undefined`.
+ */
+export function isBailed(value: any) {
+  return value !== null && value !== false && value !== undefined
+}
+
+/** Extract the parameter tuple from a function type. */
+export type Parameters<F> = F extends (...args: infer P) => any ? P : never
+/** Extract the return type from a function type. */
+export type ReturnType<F> = F extends (...args: any) => infer R ? R : never
+/** Extract the explicit `this` type from a function type. */
+export type ThisType<F> = F extends (this: infer T, ...args: any) => any ? T : never
+
+/**
+ * Event dispatch strategy used by the event service.
+ *
+ * `emit` runs synchronous listeners without awaiting them, `parallel` awaits
+ * all listeners together, `serial` awaits them in order until one bails,
+ * `bail` stops on the first synchronous bail value, and `waterfall` composes
+ * listeners around a final `next` callback.
+ */
+export type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
+
+declare module './context.ts' {
+  export interface Context {
+    /* eslint-disable max-len */
+    /**
+     * Dispatch an event, running all listeners concurrently.
+     *
+     * @param name — the event name.
+     * @param args — arguments passed to every listener.
+     * @returns a promise resolving once every listener has settled.
+     */
+    parallel<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promise<void>
+    /** Same as above, with an explicit `this` for listeners (also used for filtering). */
+    parallel<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promise<void>
+    /**
+     * Dispatch an event synchronously, ignoring listener return values.
+     *
+     * @param name — the event name.
+     * @param args — arguments passed to every listener.
+     */
+    emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void
+    /** Same as above, with an explicit `this` for listeners (also used for filtering). */
+    emit<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): void
+    /**
+     * Dispatch an event, awaiting listeners in order until one bails.
+     *
+     * @param name — the event name.
+     * @param args — arguments passed to each listener.
+     * @returns the first bail value (non-null, non-false, non-undefined), if any.
+     */
+    serial<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
+    /** Same as above, with an explicit `this` for listeners (also used for filtering). */
+    serial<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
+    /**
+     * Dispatch an event, calling listeners in order until one bails.
+     *
+     * @param name — the event name.
+     * @param args — arguments passed to each listener.
+     * @returns the first bail value (non-null, non-false, non-undefined), if any.
+     */
+    bail<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+    /** Same as above, with an explicit `this` for listeners (also used for filtering). */
+    bail<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+    /**
+     * Dispatch an event whose last argument is a `next` continuation.
+     *
+     * Each listener wraps the rest of the chain: calling `next()` invokes the
+     * next listener (finally the built-in behavior); not calling it vetoes.
+     *
+     * @param name — the event name.
+     * @param args — listener arguments; the final one is the innermost `next`.
+     * @returns the outermost listener's return value.
+     */
+    waterfall<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+    /** Same as above, with an explicit `this` for listeners (also used for filtering). */
+    waterfall<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+    /**
+     * Register an event listener owned by the current fiber.
+     *
+     * @param name — the event name to listen for.
+     * @param listener — called with the dispatch arguments.
+     * @param options — listener options; a boolean is shorthand for `prepend`.
+     * @returns a disposer removing the listener; `true` if it was still registered.
+     */
+    on<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
+    /**
+     * Same as `on()`, but the listener disposes itself after its first call.
+     *
+     * @param name — the event name to listen for.
+     * @param listener — called at most once with the dispatch arguments.
+     * @param options — listener options; a boolean is shorthand for `prepend`.
+     * @returns a disposer removing the listener; `true` if it was still registered.
+     */
+    once<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
+    /* eslint-enable max-len */
+  }
+}
+
+/** Options accepted by `ctx.on()` and `ctx.once()`. */
+export interface EventOptions {
+  /** Add the listener before existing listeners for the same event. */
+  prepend?: boolean
+  /** Receive the event regardless of context filter checks. */
+  global?: boolean
+}
+
+/** Registered listener record stored by the event service. */
+export interface Hook extends EventOptions {
+  ctx: Context
+  callback: (...args: any[]) => any
+}
+
+/**
+ * Event bus installed as `ctx.events` and mixed into every context.
+ *
+ * The service supports concurrent, synchronous, serial, bail, and waterfall
+ * dispatch and automatically disposes listeners with their owning fiber.
+ */
+export class EventsService {
+  _hooks: Record<keyof any, Hook[]> = {}
+
+  constructor(private ctx: Context) {
+    defineProperty(this, symbols.tracker, {
+      property: 'ctx',
+      noShadow: true,
+    })
+
+    this.on('internal/listener', function (this: Context, name, listener, options: EventOptions) {
+      if (name === 'internal/update' && !options.global) {
+        const hooks = this.fiber._hooks['internal/update'] ??= new DisposableList()
+        const method = options.prepend ? 'unshift' : 'push'
+        return hooks[method](listener)
+      }
+    })
+
+    this.on('internal/update', function (config, noSave, next) {
+      const cbs = [...this._hooks['internal/update'] || []]
+      const _next = () => {
+        const cb = cbs.shift() ?? next
+        return cb.call(this, config, noSave, _next)
+      }
+      return _next()
+    }, { global: true, prepend: true })
+  }
+
+  /**
+   * Resolve listeners for one dispatch and apply context filtering.
+   *
+   * @param type — the dispatch mode, reported on `internal/dispatch`.
+   * @param args — the raw dispatch arguments; consumed up to the event name.
+   * @returns the matching listener callbacks, bound to the dispatch `this`.
+   */
+  dispatch(type: string, args: any[]) {
+    const thisArg = typeof args[0] === 'object' || typeof args[0] === 'function' ? args.shift() : null
+    const name: string = args.shift()
+    if (!name.startsWith('internal/')) {
+      this.emit('internal/dispatch', type, name, args, thisArg)
+    }
+    const filter = thisArg?.[Context.filter]
+    return (this._hooks[name] || [])
+      .filter(hook => hook.global || !filter || filter.call(thisArg, hook.ctx))
+      .map(hook => hook.callback.bind(thisArg))
+  }
+
+  /**
+   * Run listeners concurrently and wait for all of them.
+   *
+   * @param args — optional `this`, the event name, then listener arguments.
+   * @returns a promise resolving once every listener has settled.
+   */
+  async parallel(...args: any[]) {
+    const results = await Promise.allSettled(this.dispatch('emit', args).map(async cb => cb(...args)))
+    const errors = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+    if (errors.length) throw new AggregateError(errors.map(error => error.reason))
+  }
+
+  /**
+   * Run listeners synchronously without waiting for returned promises.
+   *
+   * @param args — optional `this`, the event name, then listener arguments.
+   */
+  emit(...args: any[]) {
+    this.dispatch('emit', args).map(cb => cb(...args))
+  }
+
+  /**
+   * Run listeners in order, awaiting each, until one returns a bail value.
+   *
+   * @param args — optional `this`, the event name, then listener arguments.
+   * @returns the first bail value (see {@link isBailed}), if any.
+   */
+  async serial(...args: any[]) {
+    for (const cb of this.dispatch('serial', args)) {
+      const result = await cb(...args)
+      if (isBailed(result)) return result
+    }
+  }
+
+  /**
+   * Run listeners synchronously until one returns a bail value.
+   *
+   * @param args — optional `this`, the event name, then listener arguments.
+   * @returns the first bail value (see {@link isBailed}), if any.
+   */
+  bail(...args: any[]) {
+    for (const cb of this.dispatch('bail', args)) {
+      const result = cb(...args)
+      if (isBailed(result)) return result
+    }
+  }
+
+  /**
+   * Compose listeners around the final `next` callback.
+   *
+   * The last dispatch argument is treated as the innermost `next`. Listeners
+   * run outermost-first; a listener that does not call `next()` vetoes the
+   * rest of the chain, including the built-in behavior.
+   *
+   * @param args — optional `this`, the event name, listener arguments, then `next`.
+   * @returns the outermost listener's return value.
+   */
+  waterfall(...args: any[]) {
+    const cbs = this.dispatch('waterfall', args)
+    const inner = args.pop()
+    const next = () => {
+      const cb = cbs.shift() ?? inner
+      return cb(...args)
+    }
+    args.push(next)
+    return next()
+  }
+
+  /**
+   * Store a listener record as an effect on the current fiber.
+   *
+   * @param label — effect label shown in fiber diagnostics.
+   * @param hooks — the listener list for one event.
+   * @param callback — the listener to store.
+   * @param options — placement and filtering options.
+   * @returns a disposer that unregisters the listener.
+   */
+  register(label: string, hooks: Hook[], callback: any, options: EventOptions): () => void {
+    const method = options.prepend ? 'unshift' : 'push'
+    return this.ctx.fiber.effect(() => {
+      hooks[method]({ ctx: this.ctx, callback, ...options })
+      return () => this.unregister(hooks, callback)
+    }, label)
+  }
+
+  /**
+   * Remove a stored listener record.
+   *
+   * @param hooks — the listener list for one event.
+   * @param callback — the listener to remove.
+   * @returns `true` if the listener was found and removed.
+   */
+  unregister(hooks: Hook[], callback: any) {
+    const index = hooks.findIndex(hook => hook.callback === callback)
+    if (index >= 0) {
+      hooks.splice(index, 1)
+      return true
+    }
+  }
+
+  /**
+   * Register an event listener owned by the current fiber.
+   *
+   * The listener is removed automatically when the fiber unloads. Throws
+   * `CordisError('INACTIVE_EFFECT')` if the fiber is already disposed.
+   *
+   * @param name — the event name to listen for.
+   * @param listener — called with the dispatch arguments.
+   * @param options — listener options; a boolean is shorthand for `prepend`.
+   * @returns a disposer removing the listener; `true` if it was still registered.
+   */
+  on(name: string | symbol, listener: (...args: any) => any, options?: boolean | EventOptions) {
+    if (typeof options !== 'object') {
+      options = { prepend: options }
+    }
+
+    // handle special events
+    this.ctx.fiber.assertActive()
+    listener = this.ctx.reflect.bind(listener)
+    const result = this.bail(this.ctx, 'internal/listener', name, listener, options)
+    if (result) return result
+
+    const hooks = this._hooks[name] ||= []
+    const label = `ctx.on(${typeof name === 'string' ? JSON.stringify(name) : name.toString()})`
+    return this.register(label, hooks, listener, options)
+  }
+
+  /**
+   * Register an event listener that disposes itself after the first call.
+   *
+   * @param name — the event name to listen for.
+   * @param listener — called at most once with the dispatch arguments.
+   * @param options — listener options; a boolean is shorthand for `prepend`.
+   * @returns a disposer removing the listener; `true` if it was still registered.
+   */
+  once(name: string, listener: (...args: any) => any, options?: boolean | EventOptions) {
+    const dispose = this.on(name, function (...args: any[]) {
+      dispose()
+      return listener.apply(this, args)
+    }, options)
+    return dispose
+  }
+}
+
+/**
+ * Built-in framework events used by core services and extension points.
+ *
+ * Plugin and status events track fiber lifecycle, service events observe
+ * dependency registration, update/get/set/listener events allow core services
+ * to intercept runtime operations, and `internal/dispatch` exposes event-bus
+ * diagnostics before public events are delivered.
+ */
+export interface Events {
+  /** A plugin fiber was created or its uid was cleared on disposal. */
+  'internal/plugin'(fiber: Fiber): void
+  /** A fiber changed lifecycle state; receives the fiber and its previous state. */
+  'internal/status'(fiber: Fiber, oldValue: FiberState): void
+  /**
+   * Resolve raw plugin config after the fiber's injections become active.
+   * @param config - the raw config for this activation.
+   * @mode waterfall
+   */
+  'internal/config'(this: Fiber, config: any, next: () => any): any
+  /** Interception hook for a service binding (no core producer). */
+  'internal/service'(this: Context, name: string, value: any): void
+  /** Waterfall: a fiber config update is being applied; skip `next()` to veto. */
+  'internal/update'(this: Fiber, config: any, noSave: boolean, next: () => void | Promise<void>): void | Promise<void>
+  /** Waterfall: a service is being read through the context proxy. */
+  'internal/get'(ctx: Context, name: string, error: Error, next: () => any): any
+  /** Waterfall: a service is being written through the context proxy. */
+  'internal/set'(ctx: Context, name: string, value: any, error: Error, next: () => boolean): boolean
+  /** Bail: a listener is being registered; a non-null result replaces registration. */
+  'internal/listener'(this: Context, name: string, listener: any, prepend: boolean): void
+  /** An event is being dispatched to listeners (fired for non-internal events only). */
+  'internal/dispatch'(mode: DispatchMode, name: string, args: any[], thisArg: any): void
+}