✨ Introduce context APIs for algebraic effects (#1101)

One of the most powerful patterns that we've uncovered in the past
couple of years of writing Effection code in production is the ability
to contextualize an API so that they can be decorated in order to
alter its behavior at any point. In other circles, this capability is
known as "Algebraic Effects" and "Contextual Effects".

With them, we can build all manner of constructs with a single primitive that
would otherwise require many unique mechanisms. These include things
like:

- dependency injection
- mocking inside tests with test doubles
- adding instrumentation such as OTEL spans and metrics colleciton to
- existing interfaces
- wrapping stuff in database transactions

This functionality was available as an external
extension (https://frontside.com/effection/x/context-api), but the
pattern has proven so powerful that we're bringing it directly into
Effection core. Among other things, this will allow us to provide the
type of orthogonal observability that we need to build the Effection
inspector without having to change the library itself in order to
accomodate it.

This change brings the context API functionality directly into
Effection. To create an API, call `createApi()` with the "core"
functionality, where the "core" is how it will behave without any
modification.

```ts
// logging.ts
export const Logging = createApi("Logging", {
  *log(...values: unknown[]) {
    console.log(...values);
  }
})

// export member operations so they can be use standalone
export const { log } = Logging.operations;
```

```ts
import { log } from "./logging.ts"

export function* example() {
 // do stuff
 yield* log("just did stuff");
}
```

```ts
// Override it contextually only inside this scope
yield* logging.around({
  *log(args, next) {
    yield* next(...args.map(v => `[CUSTOM] ${v}`));
  }
});
```

Apis can be enhanced directly from a `Scope` as well:

```ts
import { Logging } from "./logging.ts";

function enhanceLogging(scope: Scope) {
  scope.around(Logging, {
    *log(args, next) {
      yield* next(...args.map(v => `[CUSTOM] ${v}`));
    }
  });
}

```

As an example, and as the api necessary to implement the inspector,
this provides a Scope api which provides instrumentation for core
Effection operations. Such as create(), destroy(), set(), and delete()
for scopes.

Author: cowboyd

deno.json

@@ -12,7 +12,7 @@
     "build:jsr": "deno run -A tasks/build-jsr.ts"
   },
   "lint": {
-    "rules": { "exclude": ["prefer-const", "require-yield"] },
+    "rules": { "exclude": ["prefer-const", "require-yield", "ban-types"] },
     "exclude": ["build", "docs", "tasks"],
     "plugins": ["lint/prefer-let.ts"]
   },

experimental.ts

@@ -0,0 +1 @@
+export * from "./lib/api.ts";

lib/api-internal.ts

@@ -0,0 +1,142 @@
+// deno-lint-ignore-file ban-types no-explicit-any
+import { createContext } from "./context.ts";
+import { useScope } from "./scope.ts";
+import type {
+  Api,
+  Around,
+  Context,
+  Middleware,
+  Operation,
+  Scope,
+} from "./types.ts";
+import type { ScopeInternal } from "./scope-internal.ts";
+
+export interface ApiInternal<A> extends Api<A> {
+  context: Context<{
+    capture: Partial<Around<A>>[];
+    bubble: Partial<Around<A>>[];
+  }>;
+  core: A;
+}
+
+export function createApiInternal<A extends {}>(
+  name: string,
+  core: A,
+): ApiInternal<A> {
+  let fields = Object.keys(core) as (keyof A)[];
+
+  let context = createContext(`api::${name}`) as ApiInternal<A>["context"];
+
+  let api: ApiInternal<A> = {
+    core,
+    context,
+    invoke: (scope, key, args) => {
+      let handle = createHandle(api, scope);
+      let member = handle[key];
+      if (typeof member === "function") {
+        return member(...args);
+      } else {
+        return member;
+      }
+    },
+    around: (decorator, options = {}) => ({
+      *[Symbol.iterator]() {
+        let scope = yield* useScope();
+        scope.around(api, decorator, options);
+      },
+    }),
+    operations: fields.reduce((sum, field) => {
+      if (typeof core[field] === "function") {
+        return Object.assign(sum, {
+          [field]: (...args: any) => ({
+            *[Symbol.iterator]() {
+              let scope = yield* useScope();
+              let target = api.invoke(scope, field, args);
+
+              return isOperation(target) ? yield* target : target;
+            },
+          }),
+        });
+      } else {
+        return Object.assign(sum, {
+          [field]: {
+            *[Symbol.iterator]() {
+              let scope = yield* useScope();
+              let target = api.invoke(scope, field, [] as any);
+              return isOperation(target) ? yield* target : target;
+            },
+          },
+        });
+      }
+    }, {} as Api<A>["operations"]),
+  };
+  return api;
+}
+
+function createHandle<A extends {}>(api: ApiInternal<A>, scope: Scope): A {
+  let handle = Object.create(api.core);
+  let $scope = scope as ScopeInternal;
+  for (let key of Object.keys(api.core) as Array<keyof A>) {
+    let dispatch = (args: unknown[], next: (...args: unknown[]) => unknown) => {
+      let { bubble, capture } = $scope.reduce(api.context, (sum, current) => {
+        let min = current.bubble.flatMap((around) =>
+          around[key] ? [around[key]] : []
+        );
+        let max = current.capture.flatMap((around) =>
+          around[key] ? [around[key]] : []
+        );
+
+        sum.bubble.push(...min);
+        sum.capture.unshift(...max);
+
+        return sum;
+      }, {
+        bubble: [] as Around<A>[typeof key][],
+        capture: [] as Around<A>[typeof key][],
+      });
+
+      let stack = combine(
+        capture.concat(bubble) as Middleware<unknown[], unknown>[],
+      );
+      return stack(args, next);
+    };
+
+    if (typeof api.core[key] === "function") {
+      handle[key] = (...args: unknown[]) =>
+        dispatch(args, api.core[key] as (...args: unknown[]) => unknown);
+    } else {
+      Object.defineProperty(handle, key, {
+        enumerable: true,
+        get() {
+          return dispatch([], () => api.core[key]);
+        },
+      });
+    }
+  }
+  return handle;
+}
+
+function isOperation<T>(
+  target: Operation<T> | T,
+): target is Operation<T> {
+  return target && !isNativeIterable(target) &&
+    typeof (target as Operation<T>)[Symbol.iterator] === "function";
+}
+
+function isNativeIterable(target: unknown): boolean {
+  return (
+    typeof target === "string" || Array.isArray(target) ||
+    target instanceof Map || target instanceof Set
+  );
+}
+
+function combine<TArgs extends unknown[], TReturn>(
+  middlewares: Middleware<TArgs, TReturn>[],
+): Middleware<TArgs, TReturn> {
+  if (middlewares.length === 0) {
+    return (args, next) => next(...args);
+  }
+  return middlewares.reduceRight((sum, middleware) => (args, next) =>
+    middleware(args, (...args) => sum(args, next))
+  );
+}

lib/api.ts

@@ -0,0 +1,30 @@
+// deno-lint-ignore-file ban-types
+import type { Api, Context, Operation, Scope } from "./types.ts";
+import { createApiInternal } from "./api-internal.ts";
+import type { ScopeInternal } from "./scope-internal.ts";
+
+export function createApi<A extends {}>(name: string, core: A): Api<A> {
+  return createApiInternal(name, core);
+}
+
+export const api = {
+  Scope: createApi("Scope", {
+    create() {
+      throw new TypeError(`no handler for Scope.create()`);
+    },
+    *destroy() {},
+    set(scope, context, value) {
+      return (scope as ScopeInternal).contexts[context.name] = value;
+    },
+    delete(scope, context) {
+      return delete (scope as ScopeInternal).contexts[context.name];
+    },
+  }),
+} as {
+  Scope: Api<{
+    create(parent: Scope): [Scope, () => Operation<void>];
+    destroy(scope: Scope): Operation<void>;
+    set<T>(scope: Scope, context: Context<T>, value: T): T;
+    delete<T>(scope: Scope, context: Context<T>): boolean;
+  }>;
+};

lib/scope-internal.ts

@@ -1,11 +1,34 @@
+import type { ApiInternal } from "./api-internal.ts";
+import { api as effection } from "./api.ts";
 import { Children, Priority } from "./contexts.ts";
 import { Err, Ok, unbox } from "./result.ts";
 import { createTask } from "./task.ts";
 import type { Context, Operation, Scope, Task } from "./types.ts";
 import { type WithResolvers, withResolvers } from "./with-resolvers.ts";
 
+const api = effection.Scope;
+
 export function createScopeInternal(
   parent?: Scope,
+): [ScopeInternal, () => Operation<void>] {
+  if (!parent) {
+    let [global, destroy] = buildScopeInternal();
+    global.around(api, {
+      create([parent]) {
+        return buildScopeInternal(parent);
+      },
+    });
+    return [global, destroy] as const;
+  } else {
+    return api.invoke(parent, "create", [parent]) as [
+      ScopeInternal,
+      () => Operation<void>,
+    ];
+  }
+}
+
+export function buildScopeInternal(
+  parent?: Scope,
 ): [ScopeInternal, () => Operation<void>] {
   let destructors = new Set<() => Operation<void>>();
 
@@ -19,7 +42,7 @@ export function createScopeInternal(
       return (contexts[context.name] ?? context.defaultValue) as T | undefined;
     },
     set<T>(context: Context<T>, value: T): T {
-      return contexts[context.name] = value;
+      return api.invoke(scope, "set", [scope, context, value]) as T;
     },
     expect<T>(context: Context<T>): T {
       let value = scope.get(context);
@@ -31,7 +54,7 @@ export function createScopeInternal(
       return value;
     },
     delete<T>(context: Context<T>): boolean {
-      return delete contexts[context.name];
+      return api.invoke(scope, "delete", [scope, context]);
     },
     hasOwn<T>(context: Context<T>): boolean {
       return !!Reflect.getOwnPropertyDescriptor(contexts, context.name);
@@ -51,52 +74,99 @@ export function createScopeInternal(
       };
     },
 
+    around<A extends {}>(
+      api: ApiInternal<A>,
+      ...params: Parameters<ApiInternal<A>["around"]>
+    ) {
+      let [around, options] = params;
+      if (!scope.hasOwn(api.context)) {
+        scope.set(api.context, { bubble: [], capture: [] });
+      }
+
+      let { bubble, capture } = scope.expect(api.context);
+
+      if (options?.capture) {
+        capture.push(around);
+      } else {
+        bubble.push(around);
+      }
+    },
+
     ensure(op: () => Operation<void>): () => void {
       destructors.add(op);
       return () => destructors.delete(op);
     },
+
+    reduce<T, S>(
+      context: Context<T>,
+      fn: (sum: S, item: T) => S,
+      initial: S,
+    ): S {
+      let sum = initial;
+      let current = contexts;
+      while (current) {
+        if (Object.hasOwn(current, context.name)) {
+          let item = current[context.name] as T;
+          if (item) {
+            sum = fn(sum, item);
+          }
+        }
+
+        current = Object.getPrototypeOf(current);
+      }
+      return sum;
+    },
   });
 
   scope.set(Priority, scope.expect(Priority) + 1);
   scope.set(Children, new Set());
   parent?.expect(Children).add(scope);
 
+  let destroy = () => api.invoke(scope, "destroy", [scope]);
+
   let unbind = parent ? (parent as ScopeInternal).ensure(destroy) : () => {};
 
   let destruction: WithResolvers<void> | undefined = undefined;
 
-  function* destroy(): Operation<void> {
-    if (destruction) {
-      return yield* destruction.operation;
-    }
-    destruction = withResolvers<void>();
-    parent?.expect(Children).delete(scope);
-    unbind();
-    let outcome = Ok();
-    try {
-      for (let destructor of destructors) {
-        try {
-          destructors.delete(destructor);
-          yield* destructor();
-        } catch (error) {
-          outcome = Err(error as Error);
-        }
+  scope.around(api, {
+    *destroy(): Operation<void> {
+      if (destruction) {
+        return yield* destruction.operation;
       }
-    } finally {
-      if (outcome.ok) {
-        destruction.resolve();
-      } else {
-        destruction.reject(outcome.error);
+      destruction = withResolvers<void>();
+      parent?.expect(Children).delete(scope);
+      unbind();
+      let outcome = Ok();
+      try {
+        for (let destructor of destructors) {
+          try {
+            destructors.delete(destructor);
+            yield* destructor();
+          } catch (error) {
+            outcome = Err(error as Error);
+          }
+        }
+      } finally {
+        if (outcome.ok) {
+          destruction.resolve();
+        } else {
+          destruction.reject(outcome.error);
+        }
       }
-    }
 
-    unbox(outcome);
-  }
+      unbox(outcome);
+    },
+  });
 
   return [scope, destroy];
 }
 
 export interface ScopeInternal extends Scope {
   contexts: Record<string, unknown>;
   ensure(op: () => Operation<void>): () => void;
+  reduce<T, TSum>(
+    context: Context<T>,
+    fn: (sum: TSum, item: T) => TSum,
+    initial: TSum,
+  ): TSum;
 }