@effectionx/context-api 0.0.1

package/README.md

@@ -0,0 +1,94 @@
+# Context Apis
+
+Often called "Algebraic Effects" or "Contextual Effects", Context apis let you
+access an operation via the context in a way that it can be easily (and
+contextually) wrapped with middleware.
+
+---
+
+Let's say that you want to define a log operation that behaves differently in
+different context. The basic form will just log values to the console.
+
+```ts
+// file logging.ts
+import { createApi } from "@effectionx/context-api";
+
+// create the `logging` api. By default, it just logs to the console.
+const logging = createApi<Logging>(
+  "logging",
+  function* log(...values: unknown[]) {
+    console.log(...values);
+  },
+);
+
+// export the logging operations.
+export const { log } = logging.operations;
+```
+
+Now you can use the logging api wherever you want:
+
+```ts
+import { log } from "./logging.ts";
+
+export function* op() {
+  yield* log(`I am in an operation`);
+}
+```
+
+However, use can use the `around` function to wrap middleware around your
+logging operation. This lets you do stuff like silence logging, or even to
+re-route it somewhere else than from the `console` completely.
+
+```ts
+import { logging } from "./logging.ts";
+
+function* initCustomLogging(externallogger) {
+  yield* logging.around({
+    *log(...values, next) {
+      externalLogger.log(...values);
+      // since we override the logger entirely, we do not invoke next.
+    },
+  });
+}
+```
+
+The best part is that the middleware is only in effect inside the scope in which
+it is installed.
+
+Middleware can be useful for automatic instrumentation. For example, let's
+assume that `fetch` was a an api called `fetching`:
+
+```ts
+import { fetch, fetching } from "./fetching.ts";
+
+function* instrumentFetch(tracer) {
+  yield* fetching.around({
+    *fetch(...args, next) {
+	  try {
+	    tracer.begin("fetch", args),
+		return yield* next(...args);
+	  } finally {
+	    tracer.end("fetch", args);
+	  }
+	}
+  })
+}
+```
+
+or mocking inside test cases:
+
+```ts
+import { fetch, fetching } from "./fetching.ts";
+
+function* useMocks() {
+  yield* fetching.around({
+    *fetch(...args, next) {
+      if (args[0] === "/my-path") {
+        return new MockResponse("my-path");
+      } else {
+        return yield* next(...args);
+      }
+    },
+  });
+}
+```

package/esm/mod.d.ts

@@ -0,0 +1,16 @@
+import { type Operation } from "effection";
+export type Around<A> = {
+    [K in keyof Operations<A>]: A[K] extends (...args: infer TArgs) => infer TReturn ? Middleware<TArgs, TReturn> : Middleware<[], A[K]>;
+};
+export interface Middleware<TArgs extends unknown[], TReturn> {
+    (args: TArgs, next: (...args: TArgs) => TReturn): TReturn;
+}
+export interface Api<A> {
+    operations: Operations<A>;
+    around: (around: Partial<Around<A>>) => Operation<void>;
+}
+export type Operations<T> = {
+    [K in keyof T]: T[K] extends ((...args: infer TArgs) => infer TReturn) ? (...args: TArgs) => TReturn : T[K] extends Operation<infer TReturn> ? Operation<TReturn> : never;
+};
+export declare function createApi<A extends {}>(name: string, handler: A): Api<A>;
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;KACrB,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAC9B,CAAC,GAAG,IAAI,EAAE,MAAM,KAAK,KAAK,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,GAClE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;CACzB,CAAC;AAEF,MAAM,WAAW,UAAU,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO;IAC1D,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC;CAC3D;AAED,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;CACzD;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;KACzB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,KAAK,KAAK,MAAM,OAAO,CAAC,GAClE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAC3B,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,GAC1D,KAAK;CACV,CAAC;AAEF,wBAAgB,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CA+CxE"}

package/esm/mod.js

@@ -0,0 +1,45 @@
+// deno-lint-ignore-file ban-types no-explicit-any
+import { createContext } from "effection";
+export function createApi(name, handler) {
+    let fields = Object.keys(handler);
+    let middleware = fields.reduce((sum, field) => {
+        return Object.assign(sum, {
+            [field]: (args, next) => next(...args),
+        });
+    }, {});
+    let context = createContext(`$api:${name}`, middleware);
+    let operations = fields.reduce((api, field) => {
+        let handle = handler[field];
+        if (typeof handle === "function") {
+            return Object.assign(api, {
+                [field]: function* (...args) {
+                    let around = yield* context.expect();
+                    let middleware = around[field];
+                    return yield* middleware(args, handle);
+                },
+            });
+        }
+        else {
+            return Object.assign(api, {
+                [field]: {
+                    *[Symbol.iterator]() {
+                        let around = yield* context.expect();
+                        let middleware = around[field];
+                        return yield* middleware([], () => handle);
+                    },
+                },
+            });
+        }
+    }, {});
+    function* around(around) {
+        let current = yield* context.expect();
+        yield* context.set(fields.reduce((sum, field) => {
+            let prior = current[field];
+            let middleware = around[field];
+            return Object.assign(sum, {
+                [field]: (args, next) => middleware(args, (...args) => prior(args, next)),
+            });
+        }, Object.assign({}, current)));
+    }
+    return { operations, around };
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@effectionx/context-api",
+  "version": "0.0.1",
+  "author": "engineering@frontside.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thefrontside/effectionx.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/thefrontside/effectionx/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    }
+  },
+  "engines": {
+    "node": ">= 16"
+  },
+  "sideEffects": false,
+  "_generatedBy": "dnt@dev"
+}

package/script/mod.d.ts

@@ -0,0 +1,16 @@
+import { type Operation } from "effection";
+export type Around<A> = {
+    [K in keyof Operations<A>]: A[K] extends (...args: infer TArgs) => infer TReturn ? Middleware<TArgs, TReturn> : Middleware<[], A[K]>;
+};
+export interface Middleware<TArgs extends unknown[], TReturn> {
+    (args: TArgs, next: (...args: TArgs) => TReturn): TReturn;
+}
+export interface Api<A> {
+    operations: Operations<A>;
+    around: (around: Partial<Around<A>>) => Operation<void>;
+}
+export type Operations<T> = {
+    [K in keyof T]: T[K] extends ((...args: infer TArgs) => infer TReturn) ? (...args: TArgs) => TReturn : T[K] extends Operation<infer TReturn> ? Operation<TReturn> : never;
+};
+export declare function createApi<A extends {}>(name: string, handler: A): Api<A>;
+//# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;KACrB,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAC9B,CAAC,GAAG,IAAI,EAAE,MAAM,KAAK,KAAK,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,GAClE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;CACzB,CAAC;AAEF,MAAM,WAAW,UAAU,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO;IAC1D,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC;CAC3D;AAED,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;CACzD;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;KACzB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,KAAK,KAAK,MAAM,OAAO,CAAC,GAClE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAC3B,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,GAC1D,KAAK;CACV,CAAC;AAEF,wBAAgB,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CA+CxE"}

package/script/mod.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApi = createApi;
+// deno-lint-ignore-file ban-types no-explicit-any
+const effection_1 = require("effection");
+function createApi(name, handler) {
+    let fields = Object.keys(handler);
+    let middleware = fields.reduce((sum, field) => {
+        return Object.assign(sum, {
+            [field]: (args, next) => next(...args),
+        });
+    }, {});
+    let context = (0, effection_1.createContext)(`$api:${name}`, middleware);
+    let operations = fields.reduce((api, field) => {
+        let handle = handler[field];
+        if (typeof handle === "function") {
+            return Object.assign(api, {
+                [field]: function* (...args) {
+                    let around = yield* context.expect();
+                    let middleware = around[field];
+                    return yield* middleware(args, handle);
+                },
+            });
+        }
+        else {
+            return Object.assign(api, {
+                [field]: {
+                    *[Symbol.iterator]() {
+                        let around = yield* context.expect();
+                        let middleware = around[field];
+                        return yield* middleware([], () => handle);
+                    },
+                },
+            });
+        }
+    }, {});
+    function* around(around) {
+        let current = yield* context.expect();
+        yield* context.set(fields.reduce((sum, field) => {
+            let prior = current[field];
+            let middleware = around[field];
+            return Object.assign(sum, {
+                [field]: (args, next) => middleware(args, (...args) => prior(args, next)),
+            });
+        }, Object.assign({}, current)));
+    }
+    return { operations, around };
+}

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}