context 2.0.9 → 3.0.0-dev-040354

package/README.md

@@ -5,32 +5,86 @@ It allows you to keep reference for shared variables, and access them down in yo
 
 ## How Context Works?
 
-The way context works is quite simple. Creating a context initializes a closure with a context storage object. When you run your context call, it takes your values, and places them in the context storage object. When your function finishes running, the context is cleared.
-
-![image](https://user-images.githubusercontent.com/11255103/137119151-6912d3f1-ab48-4c91-a426-76af8abc8c55.png)
+The way context works is quite simple. Creating a context initializes a closure with a context storage object. When you run your context call, it takes your values, and places them in the context's closure. When your function finishes running, the context is cleared.
 
 The reason the context is cleared after its run is so that items can't override one another. Assume you have two running the same async function twice, and it writes to the context, expecting to read the value somewhere down the line. Now you have two competing consumers of this single resource, and one eventually get the wrong value since they both read from and write to the same place.
 
 ## API Reference
 
-Context tries to mimic the behavior of Javascript scopes without actually being in the same scopes, and the API is built around context initialization, setting of values within the context and retrieving values.
+### Top Level Exports
+
+The context package exports these two functions:
+
+- `createContext`: Creates a new context.
+- `createCascade`: Creates a new cascading context.
+
+## createContext()
+
+Create context is the minimal implementation of context. It allows propagation of values down in your function call.
+
+createContext takes a single argument - defaultContextValue. This value is used when not withing a running context.
+
+### Arguments
+
+| Argument            | Type  | Optional? | Description                                                  |
+| ------------------- | ----- | --------- | ------------------------------------------------------------ |
+| defaultContextValue | `any` | Yes       | The default value to use when not withing a running context. |
 
-### createContext()
+### Returned object
 
-Context's default export, it creates a context singleton object that can later be referenced.
+`createContext` returns an object containing the following functions:
+
+- `use`: Returns the current context value, or the default value when not withing a running context.
+- `useX`: Returns the current context, throws an error if not within a running context or the context is undefined. `useX` will throw even if a default value is provided.
+- `run`: Runs the context, passing the given value into the context.
+
+**Note About Typescript Usage**
+For convenience, `use` assumes we're alwyas inside a context. If you want to have runtime safety, you can use `useX` instead to make sure you're excplicitly using a defined context.
+
+### Usage Example
 
 ```js
-// ctx.js
-import { createContext } from 'context';
+const context = createContext(0); // Create a context with a default value of 0.
 
-export default createContext(); // { run: ƒ, bind: ƒ, use: ƒ, useX: ƒ }
+function myFunc() {
+  context.run(100, someOtherFunc); // Run the context with a value of 100.
+}
+
+function someOtherFunc() {
+  const number = context.use(); // Returns the value of the context.
+}
 ```
 
-createContext also accepts an initialization function that's run every time ctx.run is called. It allows intercepting the context initialization and adding custom logic, or default values.
-The init function is passed the context object run was called with, and the parent context if it was called within a previously created context. The init function needs to return the desired context object.
+## createCascade()
+
+`createCascade` is a more advanced version of `createContext` that allows you to create cascading contexts. It assumes the value is always an object, and when nesting context layers, it merges their values together.
+
+`createCascade` does not take a default value, but an initializer function instead. This initializer is called on each `run` call, and it allows you to modify or augment the context value being passed down. The init function is passed the context object run was called with, and the parent context if it was called within a previously created context. The init function needs to return the desired context object.
+
+### Arguments
+
+| Argument    | Type       | Optional? | Description                                                  |
+| ----------- | ---------- | --------- | ------------------------------------------------------------ |
+| initializer | `Function` | Yes       | The initializer function to use when creating a new context. |
+
+The initializer function can either return the the next context object. If null is returned itself, the initializer will take no effect.
+The initializer receives the context object, and the parent context object, if present.
+
+### Returned object
+
+`createCascade` returns an object containing the following functions:
+
+- `use`: Returns the current context value.
+- `useX`: Returns the current context, throws an error if not within a running context or the context is undefined.
+- `run`: Runs the context, passing the given value into the context. Merges the given value with the parent context if it exists, while not overriding the parent context.
+- `bind`: Binds a given function to the context. Allows for delayd execution of a function as if it was called within the context.
+
+### Usage Examples
+
+#### Initializer Function
 
 ```js
-createContext((ctx, parentContext) => {
+createCascade((ctx, parentContext) => {
   if (parentContext === null) {
     // we're at the top level
     // so let's add a default cart object
@@ -44,7 +98,7 @@ createContext((ctx, parentContext) => {
 });
 ```
 
-### run()
+#### run()
 
 Runs a callback function within the context. It takes an object referencing the data you want to store within your context, and a callback function to run.
 
@@ -117,6 +171,24 @@ function getProductData(productId) {
 }
 ```
 
+## Typescript Support
+
+both `createContext` and `createCascade` have full typescript support. To gain the full benefits of typescript within your context, it is best to annotate your context with its types:
+
+```ts
+const someContext = createContext<number>(0);
+
+const someCascadeContext = createCascade<{
+  username: string;
+  firstName: string;
+  middleName?: string;
+  lastName: string;
+  age: number;
+}>();
+```
+
+This meakes sure that all the functions (`run`, `use`, `useX` and `bind`) will be aware of these types, and either accept them as inputs, or add them to the return value.
+
 ## Troubleshooting
 
 ### Working with async functions/promises

package/dist/cjs/context.development.js

@@ -4,49 +4,55 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var vestUtils = require('vest-utils');
 
-// eslint-disable-next-line max-lines-per-function
-function createContext(init) {
-    var storage = {};
+function createContext(defaultContextValue) {
+    var contextValue = undefined;
     return {
-        bind: bind,
         run: run,
         use: use,
         useX: useX
     };
+    function use() {
+        return vestUtils.defaultTo(contextValue, defaultContextValue);
+    }
     function useX(errorMessage) {
-        var ctx = use();
-        vestUtils.invariant(ctx, vestUtils.defaultTo(errorMessage, 'Context was used after it was closed'));
-        return ctx;
+        var contextValue = use();
+        vestUtils.invariant(contextValue, vestUtils.defaultTo(errorMessage, 'Context was used after it was closed'));
+        return contextValue;
     }
-    function run(ctxRef, fn) {
-        var _a;
+    function run(value, cb) {
         var parentContext = use();
-        var out = vestUtils.assign({}, parentContext ? parentContext : {}, (_a = vestUtils.optionalFunctionValue(init, ctxRef, parentContext)) !== null && _a !== void 0 ? _a : ctxRef);
-        var ctx = set(Object.freeze(out));
-        var res = fn(ctx);
-        storage.ctx = parentContext;
+        contextValue = value;
+        var res = cb();
+        contextValue = parentContext;
         return res;
     }
-    function bind(ctxRef, fn) {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore - this one's pretty hard to get right
-        var returnedFn = function () {
+}
+function createCascade(init) {
+    var ctx = createContext();
+    return {
+        bind: bind,
+        run: run,
+        use: ctx.use,
+        useX: ctx.useX
+    };
+    function run(value, fn) {
+        var _a;
+        var parentContext = ctx.use();
+        var out = vestUtils.assign({}, parentContext ? parentContext : {}, (_a = vestUtils.optionalFunctionValue(init, value, parentContext)) !== null && _a !== void 0 ? _a : value);
+        return ctx.run(Object.freeze(out), fn);
+    }
+    function bind(value, fn) {
+        return function () {
             var runTimeArgs = [];
             for (var _i = 0; _i < arguments.length; _i++) {
                 runTimeArgs[_i] = arguments[_i];
             }
-            return run(ctxRef, function () {
+            return run(value, function () {
                 return fn.apply(void 0, runTimeArgs);
             });
         };
-        return returnedFn;
-    }
-    function use() {
-        return storage.ctx;
-    }
-    function set(value) {
-        return (storage.ctx = value);
     }
 }
 
+exports.createCascade = createCascade;
 exports.createContext = createContext;

package/dist/cjs/context.production.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var t=require("vest-utils");exports.createContext=function(e){function n(n,o){var i,a=r();return n=t.assign({},a||{},null!==(i=t.optionalFunctionValue(e,n,a))&&void 0!==i?i:n),o=o(i=u.ctx=Object.freeze(n)),u.ctx=a,o}function r(){return u.ctx}var u={};return{bind:function(t,e){return function(){for(var r=[],u=0;u<arguments.length;u++)r[u]=arguments[u];return n(t,(function(){return e.apply(void 0,r)}))}},run:n,use:r,useX:function(e){var n=r();return t.invariant(n,t.defaultTo(e,"Context was used after it was closed")),n}}};
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("vest-utils");function n(n){function r(){return e.defaultTo(t,n)}var t=void 0;return{run:function(e,n){var u=r();return t=e,e=n(),t=u,e},use:r,useX:function(n){var t=r();return e.invariant(t,e.defaultTo(n,"Context was used after it was closed")),t}}}exports.createCascade=function(r){function t(n,t){var o,a=u.use();return n=e.assign({},a||{},null!==(o=e.optionalFunctionValue(r,n,a))&&void 0!==o?o:n),u.run(Object.freeze(n),t)}var u=n();return{bind:function(e,n){return function(){for(var r=[],u=0;u<arguments.length;u++)r[u]=arguments[u];return t(e,(function(){return n.apply(void 0,r)}))}},run:t,use:u.use,useX:u.useX}},exports.createContext=n;

package/dist/es/context.development.js

@@ -1,48 +1,53 @@
-import { invariant, defaultTo, assign, optionalFunctionValue } from 'vest-utils';
+import { defaultTo, invariant, assign, optionalFunctionValue } from 'vest-utils';
 
-// eslint-disable-next-line max-lines-per-function
-function createContext(init) {
-    var storage = {};
+function createContext(defaultContextValue) {
+    var contextValue = undefined;
     return {
-        bind: bind,
         run: run,
         use: use,
         useX: useX
     };
+    function use() {
+        return defaultTo(contextValue, defaultContextValue);
+    }
     function useX(errorMessage) {
-        var ctx = use();
-        invariant(ctx, defaultTo(errorMessage, 'Context was used after it was closed'));
-        return ctx;
+        var contextValue = use();
+        invariant(contextValue, defaultTo(errorMessage, 'Context was used after it was closed'));
+        return contextValue;
     }
-    function run(ctxRef, fn) {
-        var _a;
+    function run(value, cb) {
         var parentContext = use();
-        var out = assign({}, parentContext ? parentContext : {}, (_a = optionalFunctionValue(init, ctxRef, parentContext)) !== null && _a !== void 0 ? _a : ctxRef);
-        var ctx = set(Object.freeze(out));
-        var res = fn(ctx);
-        storage.ctx = parentContext;
+        contextValue = value;
+        var res = cb();
+        contextValue = parentContext;
         return res;
     }
-    function bind(ctxRef, fn) {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore - this one's pretty hard to get right
-        var returnedFn = function () {
+}
+function createCascade(init) {
+    var ctx = createContext();
+    return {
+        bind: bind,
+        run: run,
+        use: ctx.use,
+        useX: ctx.useX
+    };
+    function run(value, fn) {
+        var _a;
+        var parentContext = ctx.use();
+        var out = assign({}, parentContext ? parentContext : {}, (_a = optionalFunctionValue(init, value, parentContext)) !== null && _a !== void 0 ? _a : value);
+        return ctx.run(Object.freeze(out), fn);
+    }
+    function bind(value, fn) {
+        return function () {
             var runTimeArgs = [];
             for (var _i = 0; _i < arguments.length; _i++) {
                 runTimeArgs[_i] = arguments[_i];
             }
-            return run(ctxRef, function () {
+            return run(value, function () {
                 return fn.apply(void 0, runTimeArgs);
             });
         };
-        return returnedFn;
-    }
-    function use() {
-        return storage.ctx;
-    }
-    function set(value) {
-        return (storage.ctx = value);
     }
 }
 
-export { createContext };
+export { createCascade, createContext };

package/dist/es/context.production.js

@@ -1 +1 @@
-import{invariant as t,defaultTo as n,assign as r,optionalFunctionValue as e}from"vest-utils";export function createContext(u){function o(t,n){var o,f=c();return t=r({},f||{},null!==(o=e(u,t,f))&&void 0!==o?o:t),n=n(o=i.ctx=Object.freeze(t)),i.ctx=f,n}function c(){return i.ctx}var i={};return{bind:function(t,n){return function(){for(var r=[],e=0;e<arguments.length;e++)r[e]=arguments[e];return o(t,(function(){return n.apply(void 0,r)}))}},run:o,use:c,useX:function(r){var e=c();return t(e,n(r,"Context was used after it was closed")),e}}}
+import{defaultTo as n,invariant as r,assign as t,optionalFunctionValue as u}from"vest-utils";function e(t){function u(){return n(e,t)}var e=void 0;return{run:function(n,r){var t=u();return e=n,n=r(),e=t,n},use:u,useX:function(t){var e=u();return r(e,n(t,"Context was used after it was closed")),e}}}function o(n){function r(r,e){var i,s=o.use();return r=t({},s||{},null!==(i=u(n,r,s))&&void 0!==i?i:r),o.run(Object.freeze(r),e)}var o=e();return{bind:function(n,t){return function(){for(var u=[],e=0;e<arguments.length;e++)u[e]=arguments[e];return r(n,(function(){return t.apply(void 0,u)}))}},run:r,use:o.use,useX:o.useX}}export{o as createCascade,e as createContext};

package/dist/umd/context.development.js

@@ -4,51 +4,57 @@
   (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.context = {}, global['vest-utils']));
 }(this, (function (exports, vestUtils) { 'use strict';
 
-  // eslint-disable-next-line max-lines-per-function
-  function createContext(init) {
-      var storage = {};
+  function createContext(defaultContextValue) {
+      var contextValue = undefined;
       return {
-          bind: bind,
           run: run,
           use: use,
           useX: useX
       };
+      function use() {
+          return vestUtils.defaultTo(contextValue, defaultContextValue);
+      }
       function useX(errorMessage) {
-          var ctx = use();
-          vestUtils.invariant(ctx, vestUtils.defaultTo(errorMessage, 'Context was used after it was closed'));
-          return ctx;
+          var contextValue = use();
+          vestUtils.invariant(contextValue, vestUtils.defaultTo(errorMessage, 'Context was used after it was closed'));
+          return contextValue;
       }
-      function run(ctxRef, fn) {
-          var _a;
+      function run(value, cb) {
           var parentContext = use();
-          var out = vestUtils.assign({}, parentContext ? parentContext : {}, (_a = vestUtils.optionalFunctionValue(init, ctxRef, parentContext)) !== null && _a !== void 0 ? _a : ctxRef);
-          var ctx = set(Object.freeze(out));
-          var res = fn(ctx);
-          storage.ctx = parentContext;
+          contextValue = value;
+          var res = cb();
+          contextValue = parentContext;
           return res;
       }
-      function bind(ctxRef, fn) {
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-ignore - this one's pretty hard to get right
-          var returnedFn = function () {
+  }
+  function createCascade(init) {
+      var ctx = createContext();
+      return {
+          bind: bind,
+          run: run,
+          use: ctx.use,
+          useX: ctx.useX
+      };
+      function run(value, fn) {
+          var _a;
+          var parentContext = ctx.use();
+          var out = vestUtils.assign({}, parentContext ? parentContext : {}, (_a = vestUtils.optionalFunctionValue(init, value, parentContext)) !== null && _a !== void 0 ? _a : value);
+          return ctx.run(Object.freeze(out), fn);
+      }
+      function bind(value, fn) {
+          return function () {
               var runTimeArgs = [];
               for (var _i = 0; _i < arguments.length; _i++) {
                   runTimeArgs[_i] = arguments[_i];
               }
-              return run(ctxRef, function () {
+              return run(value, function () {
                   return fn.apply(void 0, runTimeArgs);
               });
           };
-          return returnedFn;
-      }
-      function use() {
-          return storage.ctx;
-      }
-      function set(value) {
-          return (storage.ctx = value);
       }
   }
 
+  exports.createCascade = createCascade;
   exports.createContext = createContext;
 
   Object.defineProperty(exports, '__esModule', { value: true });

package/dist/umd/context.production.js

@@ -1 +1 @@
-"use strict";!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports,require("vest-utils")):"function"==typeof define&&define.amd?define(["exports","vest-utils"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).context={},e["vest-utils"])}(this,(function(e,t){e.createContext=function(e){function n(n,i){var r,f=u();return n=t.assign({},f||{},null!==(r=t.optionalFunctionValue(e,n,f))&&void 0!==r?r:n),i=i(r=o.ctx=Object.freeze(n)),o.ctx=f,i}function u(){return o.ctx}var o={};return{bind:function(e,t){return function(){for(var u=[],o=0;o<arguments.length;o++)u[o]=arguments[o];return n(e,(function(){return t.apply(void 0,u)}))}},run:n,use:u,useX:function(e){var n=u();return t.invariant(n,t.defaultTo(e,"Context was used after it was closed")),n}}},Object.defineProperty(e,"__esModule",{value:!0})}));
+"use strict";!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports,require("vest-utils")):"function"==typeof define&&define.amd?define(["exports","vest-utils"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).context={},e["vest-utils"])}(this,(function(e,t){function n(e){function n(){return t.defaultTo(u,e)}var u=void 0;return{run:function(e,t){var r=n();return u=e,e=t(),u=r,e},use:n,useX:function(e){var u=n();return t.invariant(u,t.defaultTo(e,"Context was used after it was closed")),u}}}e.createCascade=function(e){function u(n,u){var o,i=r.use();return n=t.assign({},i||{},null!==(o=t.optionalFunctionValue(e,n,i))&&void 0!==o?o:n),r.run(Object.freeze(n),u)}var r=n();return{bind:function(e,t){return function(){for(var n=[],r=0;r<arguments.length;r++)n[r]=arguments[r];return u(e,(function(){return t.apply(void 0,n)}))}},run:u,use:r.use,useX:r.useX}},e.createContext=n,Object.defineProperty(e,"__esModule",{value:!0})}));

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.9",
+  "version": "3.0.0-dev-040354",
   "license": "MIT",
   "main": "./dist/cjs/context.js",
   "types": "./types/context.d.ts",

package/types/context.d.ts

@@ -1,8 +1,15 @@
 type CB = (...args: any[]) => any;
-declare function createContext<T extends Record<string, unknown>>(init?: (ctxRef: Partial<T>, parentContext: T | void) => T | null): {
-    run: <R>(ctxRef: Partial<T>, fn: (context: T) => R) => R;
-    bind: <Fn extends CB>(ctxRef: Partial<T>, fn: Fn) => Fn;
-    use: () => T | undefined;
+declare function createContext<T extends unknown>(defaultContextValue?: T): CtxApi<T>;
+declare function createCascade<T extends Record<string, unknown>>(init?: (value: Partial<T>, parentContext: T | void) => T | null): CtxCascadeApi<T>;
+type ContextConsumptionApi<T> = {
+    use: () => T;
     useX: (errorMessage?: string) => T;
 };
-export { createContext };
+type CtxApi<T> = ContextConsumptionApi<T> & {
+    run: <R>(value: T, cb: () => R) => R;
+};
+type CtxCascadeApi<T> = ContextConsumptionApi<T> & {
+    run: <R>(value: Partial<T>, fn: () => R) => R;
+    bind: <Fn extends CB>(value: Partial<T>, fn: Fn) => Fn;
+};
+export { createContext, createCascade, CtxApi, CtxCascadeApi };