functionalscript 0.44.0 → 0.46.0

package/fjs/effects/mock/module.f.mjs

@@ -4,14 +4,48 @@
  * See `./types.ts` for the `MemOperationMap`/`RunInstance` type-level API.
  *
  * @module
+ *
+ * @import { Commands, Effect, MatchResult, Operation } from '../types.ts'
+ * @import { MemOperationMap, PartialMemOperationMap, RunInstance } from './types.ts'
  */
-import { match } from "../module.f.mjs"
-/** @import { Operation } from '../types.ts' */
-/** @import { MemOperationMap, RunInstance } from './types.ts' */
+
+import { match, partialMatch } from "../module.f.mjs"
+import { notImplemented } from "../module.f.mjs"
+import { error } from "../../types/result/module.f.mjs"
 
 /** @type {<O extends Operation, S>(o: MemOperationMap<O, S>) => RunInstance<O, S>} */
-export const run = o => state => effect => {
-    const next = match(o)
+export const run = o => _loop(match(o))
+
+/**
+ * {@link run} for a runner that implements only part of `O`.
+ *
+ * A command in `commands` with no handler answers `error(notImplemented)`
+ * through the ordinary continuation, so a program that asks for something this
+ * runner lacks gets its control back and decides what to do. A command outside
+ * `commands` still panics — see `partialMatch`.
+ *
+ * **The injector lives here rather than at the call site.** `partialMatch`
+ * cannot build one because the shape of an answer is the runner's, not the
+ * operation's; this loop's is `(state) => [state, …]`, and writing it once here
+ * is the whole reason each runner supplies its own.
+ *
+ * @type {<O extends Operation, S>(commands: Commands<O>) => (o: PartialMemOperationMap<O, S>) => RunInstance<O, S>}
+ */
+export const partialRun = commands => o => {
+    /** @type {(command: string) => (state: any) => readonly[any, any]} */
+    const onMissing = command => state => [state, error(notImplemented(command))]
+    return _loop(partialMatch(commands, onMissing)(o))
+}
+
+/**
+ * The interpreter loop both runners share: step the effect, thread the state
+ * through the handler's transition, resume with the command's output.
+ *
+ * @type {<O extends Operation, S>(
+ *     next: <O1 extends O, T, E>(e: Effect<O1, T, E>) => MatchResult<O1, T, E, (state: S) => readonly[S, any]>
+ * ) => RunInstance<O, S>}
+ */
+const _loop = next => state => effect => {
     let s = state
     let e = effect
     while (true) {

package/fjs/effects/mock/types.d.ts

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import type { Result } from "../../types/result/types.ts";
 import type { Effect, Operation, Pr } from "../types.ts";
 /**
  * A synchronous, state-threading operation map. An entry takes the command's
@@ -12,4 +13,12 @@ import type { Effect, Operation, Pr } from "../types.ts";
 export type MemOperationMap<O extends Operation, S> = {
     readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => (state: S) => readonly [S, Pr<O, K>[1]];
 };
-export type RunInstance<O extends Operation, S> = (state: S) => <O1 extends O, T>(effect: Effect<O1, T>) => readonly [S, T];
+/**
+ * A {@link MemOperationMap} a runner may leave holes in — the state-threading
+ * counterpart of `PartialOperationMap`. An absent handler is an operation this
+ * runner does not implement, answered with `error(notImplemented)`.
+ */
+export type PartialMemOperationMap<O extends Operation, S> = {
+    readonly [K in O[0]]?: (...payload: Pr<O, K>[0]) => (state: S) => readonly [S, Pr<O, K>[1]];
+};
+export type RunInstance<O extends Operation, S> = (state: S) => <O1 extends O, T, E>(effect: Effect<O1, T, E>) => readonly [S, Result<T, E>];

package/fjs/effects/module.d.mts

@@ -1,7 +1,17 @@
+/**
+ * Impure effect interpretation: runs an `Effect` step by step against an
+ * asynchronous operation map.
+ *
+ * @module
+ *
+ * @import { Effect, Operation, ToAsyncOperationMap } from './types.ts'
+ * @import { Result } from '../types/result/types.ts'
+ */
 import type { Effect, Operation, ToAsyncOperationMap } from './types.ts';
+import type { Result } from '../types/result/types.ts';
 /**
  * @template {Operation} O
  * @param {ToAsyncOperationMap<O>} map
- * @returns {<T>(effect: Effect<O, T>) => Promise<T>}
+ * @returns {<T, E>(effect: Effect<O, T, E>) => Promise<Result<T, E>>}
  */
-export declare const asyncRun: <O extends Operation>(map: ToAsyncOperationMap<O>) => <T>(effect: Effect<O, T>) => Promise<T>;
+export declare const asyncRun: <O extends Operation>(map: ToAsyncOperationMap<O>) => <T, E>(effect: Effect<O, T, E>) => Promise<Result<T, E>>;