✨ 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

@@ -10,7 +10,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", "bench"],
     "plugins": ["lint/prefer-let.ts"]
   },

experimental.ts

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

lib/api-internal.ts

@@ -0,0 +1,174 @@
+// deno-lint-ignore-file ban-types no-explicit-any
+import { createContext } from "./context.ts";
+import type {
+  Api,
+  Around,
+  Context,
+  Effect,
+  Middleware,
+  Operation,
+  Scope,
+} from "./types.ts";
+import type { ScopeInternal } from "./scope-internal.ts";
+import { Children } from "./contexts.ts";
+import { Ok } from "./result.ts";
+
+export interface ApiInternal<A> extends Api<A> {
+  context: Context<{
+    max: Partial<Around<A>>[];
+    min: Partial<Around<A>>[];
+  }>;
+  core: A;
+  cache: WeakMap<Scope, A>;
+  invalidate(scope: Scope): void;
+}
+
+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 cache = new WeakMap<Scope, A>();
+
+  let api: ApiInternal<A> = {
+    core,
+    context,
+    cache,
+    invalidate(scope: Scope) {
+      cache.delete(scope);
+      let children = scope.get(Children);
+      if (children) {
+        for (let child of children) {
+          api.invalidate(child);
+        }
+      }
+    },
+    invoke: (scope, key, args) => {
+      let handle = cache.get(scope);
+      if (!handle) {
+        handle = createHandle(api, scope as ScopeInternal);
+        cache.set(scope, handle);
+      }
+      let member = handle[key];
+      if (typeof member === "function") {
+        return member(...args);
+      } else {
+        return member;
+      }
+    },
+    around: (decorator, options = { at: "max" }) => ({
+      *[Symbol.iterator]() {
+        let scope = (yield GetScope) as Scope;
+        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 GetScope) as Scope;
+              let target = api.invoke(scope, field, args);
+
+              return isOperation(target) ? yield* target : target;
+            },
+          }),
+        });
+      } else {
+        return Object.assign(sum, {
+          [field]: {
+            *[Symbol.iterator]() {
+              let scope = (yield GetScope) as Scope;
+              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: ScopeInternal,
+): A {
+  // there is no middleware at all for this api, so the handle _is_ the core.
+  if (!scope.get(api.context)) {
+    return api.core;
+  }
+
+  let handle = Object.create(api.core);
+
+  for (let key of Object.keys(api.core) as Array<keyof A>) {
+    let { min, max } = scope.reduce(api.context, (sum, current) => {
+      let min = current.min.flatMap((around) =>
+        around[key] ? [around[key]] : []
+      );
+      let max = current.max.flatMap((around) =>
+        around[key] ? [around[key]] : []
+      );
+
+      sum.min.push(...min);
+      sum.max.unshift(...max);
+
+      return sum;
+    }, {
+      min: [] as Around<A>[typeof key][],
+      max: [] as Around<A>[typeof key][],
+    });
+
+    let stack = combine(max.concat(min) as Middleware<unknown[], unknown>[]);
+
+    if (typeof api.core[key] === "function") {
+      handle[key] = (...args: unknown[]) =>
+        stack(args, api.core[key] as (...args: unknown[]) => unknown);
+    } else {
+      Object.defineProperty(handle, key, {
+        enumerable: true,
+        get() {
+          return stack([], () => 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))
+  );
+}
+
+const GetScope: Effect<Scope> = {
+  description: "Fast, non-typesafe lookup of co-routine scope",
+  enter: (resolve, routine) => {
+    resolve(Ok(routine.scope));
+    return (didExit) => didExit(Ok());
+  },
+};

lib/api.ts

@@ -0,0 +1,34 @@
+// 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);
+}
+
+interface ScopeApi {
+  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;
+}
+
+interface Apis {
+  Scope: Api<ScopeApi>;
+}
+
+export const api: Apis = {
+  Scope: createApi<ScopeApi>("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];
+    },
+  }),
+};