✨ Introduce context APIs for algebraic effects (#1211)

* ✨ 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.

* ⚡️ statically compute api tree at decorate time (#1183)

The computational complexity of reifying an api handle was being
deferred until the moment the api was being called, and then every
invocation paid the cost of calculating the _entire_ middleware stack
from the root all they way back to the decorate scope. The handle was
cached for subsequent invocations, but any new `around()` invalidated
that scope and every descendant, which meant that every single one
had to walk the entire scope chain on the next invocation.

The handle is now materialized at decoration time. Each api context
carries `local` (this scope's contributions), `total` (the inherited
stack), and `handle` (the assembled api). `around()` appends the new
decorator onto `local` and then walks the subtree in `install()`,
rebuilding each descendant's handle in place. Critically, the
inherited middleware stack is cached at every scope that has
middleware, so any subsequent calls to around() can begin from that
total, and do not need to walk back up the entire scope chain.

In all cases, because the api handle is computed eagerly, `invoke()`
is single context lookup and dispatch.

* ♻️ Don't use api decorator for scope.destroy

We were installing an api decorator as the method for implementing the
destroy method on scope, but this required recomputing the middleware
stack for every scope creation which is totally unecessary work.

This just puts it on a prototype method of ScopeInternal. That way,
there is one version of the function, and the default api handle, just
invokes it straight away.

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,220 @@
+// 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 { Children } from "./contexts.ts";
+import { Ok } from "./result.ts";
+
+export interface ApiInternal<A> extends Api<A> {
+  context: Context<{
+    local: Decorator<A>;
+    total: Decorator<A>;
+    handle: 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 = scope.get(api.context)?.handle ?? core;
+
+      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;
+        decorateApi(scope, 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;
+}
+
+export function decorateApi<A>(
+  scope: Scope,
+  api: ApiInternal<A>,
+  decorator: Partial<Around<A>>,
+  options?: {
+    at: "min" | "max";
+  },
+) {
+  // read existing total and local
+  let current = scope.get(api.context) ?? { total: {}, local: {} };
+
+  let local = decorate(current.local, {
+    [options?.at ?? "max"]: decorator,
+  });
+
+  if (!scope.hasOwn(api.context)) {
+    scope.set(api.context, {
+      local,
+      total: current.total,
+      handle: api.core,
+    });
+  } else {
+    current.local = local;
+  }
+
+  install(scope, api, current.total);
+}
+
+function decorate<A>(base: Decorator<A>, next: Decorator<A>): Decorator<A> {
+  return {
+    max: base.max ? next.max ? append(base.max, next.max) : base.max : next.max,
+    min: next.min ? base.min ? append(next.min, base.min) : next.min : base.min,
+  };
+}
+
+function append<A>(
+  outer: Partial<Around<A>>,
+  inner: Partial<Around<A>>,
+): Partial<Around<A>> {
+  let result: Partial<Around<A>> = { ...outer };
+  for (let key of Object.keys(inner) as (keyof A)[]) {
+    let current = outer[key];
+    let decoration = inner[key];
+    if (!current) {
+      result[key] = decoration;
+    } else {
+      let pair = [current, decoration] as Middleware<unknown[], unknown>[];
+      result[key] = combine(pair) as Around<A>[keyof A];
+    }
+  }
+  return result;
+}
+
+function install<A>(
+  scope: Scope,
+  api: ApiInternal<A>,
+  total: Decorator<A>,
+): void {
+  if (scope.hasOwn(api.context)) {
+    let context = scope.expect(api.context);
+
+    context.total = total;
+
+    total = decorate(context.total, context.local);
+
+    context.handle = createApiHandle(total, api.core);
+  }
+
+  for (let child of scope.expect(Children)) {
+    install(child, api, total);
+  }
+}
+
+function createApiHandle<A>(decoration: Decorator<A>, core: A): A {
+  let around = decoration.max
+    ? decoration.min ? append(decoration.max, decoration.min) : decoration.max
+    : decoration.min;
+  if (!around) {
+    return core;
+  }
+  let handle: A = {} as A;
+  for (let key of Object.keys(core as object) as Array<keyof A>) {
+    let middleware = around[key] as Middleware<unknown[], unknown> | undefined;
+    if (middleware) {
+      if (typeof core[key] === "function") {
+        handle[key] = ((...args: unknown[]) =>
+          middleware(args, core[key] as (...args: unknown[]) => unknown)) as A[
+            keyof A
+          ];
+      } else {
+        Object.defineProperty(handle, key, {
+          enumerable: true,
+          get() {
+            return middleware([], () => core[key]);
+          },
+        });
+      }
+    } else {
+      handle[key] = 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))
+  );
+}
+
+interface Decorator<A> {
+  min?: Partial<Around<A>>;
+  max?: Partial<Around<A>>;
+}
+
+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,36 @@
+// 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(scope) {
+      return (scope as ScopeInternal).destroy();
+    },
+    set(scope, context, value) {
+      return (scope as ScopeInternal).contexts[context.name] = value;
+    },
+    delete(scope, context) {
+      return delete (scope as ScopeInternal).contexts[context.name];
+    },
+  }),
+};