wardens 0.5.1 → 0.6.0-rc.0

package/src/__tests__/root-lifecycles.test.ts

@@ -0,0 +1,236 @@
+import type ResourceControls from '../resource-controls';
+import { create, destroy } from '../root-lifecycle';
+import bindContext from '../bind-context';
+
+describe('roots', () => {
+  describe('create', () => {
+    it('allocates the resource', async () => {
+      const config = { test: 'init-args' };
+      const Test = vi.fn(
+        async (_resource: ResourceControls, config: { test: string }) => ({
+          value: config,
+        }),
+      );
+
+      await expect(create(Test, config)).resolves.toEqual(config);
+      expect(Test).toHaveBeenCalledWith(expect.anything(), config);
+    });
+
+    describe('after initialization failure', () => {
+      it('destroys child resources in reverse order', async () => {
+        const spy = vi.fn();
+        const First = async () => ({ value: [], destroy: () => spy('1st') });
+        const Second = async () => ({ value: [], destroy: () => spy('2nd') });
+
+        const Parent = async (resource: ResourceControls) => {
+          await resource.create(First);
+          await resource.create(Second);
+          throw new Error('Testing resource initialization errors');
+        };
+
+        await expect(create(Parent)).rejects.toThrow();
+        expect(spy.mock.calls).toEqual([['2nd'], ['1st']]);
+      });
+
+      it('continues even if the children cannot be destroyed', async () => {
+        const parentError = new Error('Testing parent resource aborts');
+        const childError = new Error('Testing child resource aborts');
+        const Child = async () => ({
+          value: [],
+          destroy() {
+            throw childError;
+          },
+        });
+
+        const Parent = async (resource: ResourceControls) => {
+          await resource.create(Child);
+          await resource.create(Child);
+          throw parentError;
+        };
+
+        await expect(create(Parent)).rejects.toMatchObject({
+          cause: parentError,
+          failures: [childError, childError],
+        });
+      });
+    });
+  });
+
+  describe('destroy', () => {
+    it('deallocates the resource', async () => {
+      const spy = vi.fn<[], void>();
+      const Test = async () => ({
+        value: {},
+        destroy: spy,
+      });
+
+      const test = await create(Test);
+
+      expect(spy).not.toHaveBeenCalled();
+      await expect(destroy(test)).resolves.not.toThrow();
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it('throws an error if the object is not a resource', async () => {
+      await expect(destroy({})).rejects.toThrow(
+        'Cannot destroy object. It is not a resource.',
+      );
+    });
+
+    it('survives if the resource is already deallocated', async () => {
+      const Test = async () => ({ value: [] });
+
+      const test = await create(Test);
+      await destroy(test);
+
+      await expect(destroy(test)).resolves.not.toThrow();
+    });
+
+    it('automatically unmounts all children', async () => {
+      const spy = vi.fn();
+      const Child = async () => ({ value: [], destroy: spy });
+      async function Parent(resource: ResourceControls) {
+        await resource.create(Child);
+        return { value: [] };
+      }
+
+      const parent = await create(Parent);
+      await destroy(parent);
+
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it('throws an error if any of the children fail to close', async () => {
+      const error = new Error('Testing resource destruction errors');
+      const Child = async () => ({
+        value: [],
+        destroy() {
+          throw error;
+        },
+      });
+
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(Child);
+        return { value: [] };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toThrow(error);
+    });
+
+    it('destroys child resources in reverse order', async () => {
+      const spy = vi.fn();
+      const First = async () => ({ value: [], destroy: () => spy('1st') });
+      const Second = async () => ({ value: [], destroy: () => spy('2nd') });
+
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(First);
+        await resource.create(Second);
+        return { value: [] };
+      };
+
+      const parent = await create(Parent);
+      await destroy(parent);
+
+      expect(spy.mock.calls).toEqual([['2nd'], ['1st']]);
+    });
+
+    it('reports if multiple resources could not be destroyed', async () => {
+      const childError = new Error('Testing child resource aborts');
+      const Child = async () => ({
+        value: [],
+        destroy() {
+          throw childError;
+        },
+      });
+
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(Child);
+        await resource.create(Child);
+        return { value: [] };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toMatchObject({
+        failures: [childError, childError],
+      });
+    });
+
+    it('ensures child resources outlive their consumers', async () => {
+      const Child = async () => ({ value: [1] });
+      const Parent = async (resource: ResourceControls) => {
+        const child = await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            // The `child` resource must still be usable here.
+            expect(child).toHaveLength(1);
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await destroy(parent);
+    });
+
+    it('destroys child resources even if the parent fails to close', async () => {
+      const spy = vi.fn();
+      const Child = async () => ({ value: [], destroy: spy });
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            throw new Error('Testing parent teardown errors');
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toThrow();
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it('aggregates errors if the child resource fails to close', async () => {
+      const parentError = new Error('Testing parent resource aborts');
+      const childError = new Error('Testing child resource aborts');
+
+      const Child = async () => ({
+        value: [],
+        destroy() {
+          throw childError;
+        },
+      });
+
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            throw parentError;
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toMatchObject({
+        failures: [parentError, childError],
+      });
+    });
+
+    it('guards against creating new resources after teardown', async () => {
+      const Child = async () => ({ value: [] });
+      const Parent = async (resource: ResourceControls) => ({
+        value: bindContext(resource),
+      });
+
+      const parent = await create(Parent);
+      const { create: resourceCreate } = parent;
+      await destroy(parent);
+
+      await expect(resourceCreate(Child)).rejects.toThrow(
+        /cannot create.*after teardown/i,
+      );
+    });
+  });
+});

package/src/__tests__/roots.test.ts

@@ -0,0 +1,236 @@
+import type ResourceControls from '../resource-controls';
+import { create, destroy } from '../root-lifecycle';
+import bindContext from '../bind-context';
+
+describe('roots', () => {
+  describe('create', () => {
+    it('allocates the resource', async () => {
+      const config = { test: 'init-args' };
+      const Test = vi.fn(
+        async (_resource: ResourceControls, config: { test: string }) => ({
+          value: config,
+        }),
+      );
+
+      await expect(create(Test, config)).resolves.toEqual(config);
+      expect(Test).toHaveBeenCalledWith(expect.anything(), config);
+    });
+
+    describe('after initialization failure', () => {
+      it('destroys child resources in reverse order', async () => {
+        const spy = vi.fn();
+        const First = async () => ({ value: [], destroy: () => spy('1st') });
+        const Second = async () => ({ value: [], destroy: () => spy('2nd') });
+
+        const Parent = async (resource: ResourceControls) => {
+          await resource.create(First);
+          await resource.create(Second);
+          throw new Error('Testing resource initialization errors');
+        };
+
+        await expect(create(Parent)).rejects.toThrow();
+        expect(spy.mock.calls).toEqual([['2nd'], ['1st']]);
+      });
+
+      it('continues even if the children cannot be destroyed', async () => {
+        const parentError = new Error('Testing parent resource aborts');
+        const childError = new Error('Testing child resource aborts');
+        const Child = async () => ({
+          value: [],
+          destroy() {
+            throw childError;
+          },
+        });
+
+        const Parent = async (resource: ResourceControls) => {
+          await resource.create(Child);
+          await resource.create(Child);
+          throw parentError;
+        };
+
+        await expect(create(Parent)).rejects.toMatchObject({
+          cause: parentError,
+          failures: [childError, childError],
+        });
+      });
+    });
+  });
+
+  describe('destroy', () => {
+    it('deallocates the resource', async () => {
+      const spy = vi.fn<[], void>();
+      const Test = async () => ({
+        value: {},
+        destroy: spy,
+      });
+
+      const test = await create(Test);
+
+      expect(spy).not.toHaveBeenCalled();
+      await expect(destroy(test)).resolves.not.toThrow();
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it('throws an error if the object is not a resource', async () => {
+      await expect(destroy({})).rejects.toThrow(
+        'Cannot destroy object. It is not a resource.',
+      );
+    });
+
+    it('survives if the resource is already deallocated', async () => {
+      const Test = async () => ({ value: [] });
+
+      const test = await create(Test);
+      await destroy(test);
+
+      await expect(destroy(test)).resolves.not.toThrow();
+    });
+
+    it('automatically unmounts all children', async () => {
+      const spy = vi.fn();
+      const Child = async () => ({ value: [], destroy: spy });
+      async function Parent(resource: ResourceControls) {
+        await resource.create(Child);
+        return { value: [] };
+      }
+
+      const parent = await create(Parent);
+      await destroy(parent);
+
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it('throws an error if any of the children fail to close', async () => {
+      const error = new Error('Testing resource destruction errors');
+      const Child = async () => ({
+        value: [],
+        destroy() {
+          throw error;
+        },
+      });
+
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(Child);
+        return { value: [] };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toThrow(error);
+    });
+
+    it('destroys child resources in reverse order', async () => {
+      const spy = vi.fn();
+      const First = async () => ({ value: [], destroy: () => spy('1st') });
+      const Second = async () => ({ value: [], destroy: () => spy('2nd') });
+
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(First);
+        await resource.create(Second);
+        return { value: [] };
+      };
+
+      const parent = await create(Parent);
+      await destroy(parent);
+
+      expect(spy.mock.calls).toEqual([['2nd'], ['1st']]);
+    });
+
+    it('reports if multiple resources could not be destroyed', async () => {
+      const childError = new Error('Testing child resource aborts');
+      const Child = async () => ({
+        value: [],
+        destroy() {
+          throw childError;
+        },
+      });
+
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(Child);
+        await resource.create(Child);
+        return { value: [] };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toMatchObject({
+        failures: [childError, childError],
+      });
+    });
+
+    it('ensures child resources outlive their consumers', async () => {
+      const Child = async () => ({ value: [1] });
+      const Parent = async (resource: ResourceControls) => {
+        const child = await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            // The `child` resource must still be usable here.
+            expect(child).toHaveLength(1);
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await destroy(parent);
+    });
+
+    it('destroys child resources even if the parent fails to close', async () => {
+      const spy = vi.fn();
+      const Child = async () => ({ value: [], destroy: spy });
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            throw new Error('Testing parent teardown errors');
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toThrow();
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it('aggregates errors if the child resource fails to close', async () => {
+      const parentError = new Error('Testing parent resource aborts');
+      const childError = new Error('Testing child resource aborts');
+
+      const Child = async () => ({
+        value: [],
+        destroy() {
+          throw childError;
+        },
+      });
+
+      const Parent = async (resource: ResourceControls) => {
+        await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            throw parentError;
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toMatchObject({
+        failures: [parentError, childError],
+      });
+    });
+
+    it('guards against creating new resources after teardown', async () => {
+      const Child = async () => ({ value: [] });
+      const Parent = async (resource: ResourceControls) => ({
+        value: bindContext(resource),
+      });
+
+      const parent = await create(Parent);
+      const { create: resourceCreate } = parent;
+      await destroy(parent);
+
+      await expect(resourceCreate(Child)).rejects.toThrow(
+        /cannot create.*after teardown/i,
+      );
+    });
+  });
+});

package/src/__tests__/{types.test-d.ts → utility-types.test-d.ts}

@@ -1,4 +1,4 @@
-import { create, ResourceContext, ResourceHandle } from '../';
+import { create, ResourceControls, ResourceHandle } from '../';
 
 describe('Utility types', () => {
   describe('ResourceHandle', () => {
@@ -17,7 +17,7 @@ describe('Utility types', () => {
     });
 
     it('infers the type when the value comes from a parameter', async () => {
-      async function Test(_ctx: ResourceContext, value: { count: number }) {
+      async function Test(_ctx: ResourceControls, value: { count: number }) {
         return {
           value,
         };

package/src/{state.ts → global-weakrefs.ts}

@@ -1,4 +1,14 @@
-import type { Resource } from './types';
+import type { Resource } from './utility-types';
+
+/** Maps an external API back to the resource that created it. */
+export const resources = new WeakMap<object, RevokableResource>();
+
+/**
+ * Identifies if an object is a Wardens resource. Carries no metadata and
+ * objects are never deleted. This is separate from `resources` to avoid
+ * retaining associated objects in memory.
+ */
+export const constructed = new WeakSet<object>();
 
 export interface RevokableResource {
   resource: Resource<object>;
@@ -18,13 +28,3 @@ export interface RevokableResource {
    */
   curfew: { enforced: boolean };
 }
-
-/** Maps an external API back to the resource that created it. */
-export const resources = new WeakMap<object, RevokableResource>();
-
-/**
- * Identifies if an object is a Wardens resource. Carries no metadata and
- * objects are never deleted. This is separate from `resources` to avoid
- * retaining associated objects in memory.
- */
-export const constructed = new WeakSet<object>();

package/src/index.ts

@@ -1,4 +1,5 @@
 export { default as bindContext } from './bind-context';
-export { create, destroy } from './allocation';
-export type { Resource, ResourceHandle } from './types';
-export type { default as ResourceContext } from './resource-context';
+export { create, destroy } from './root-lifecycle';
+export { createContext } from './inherited-context';
+export type { Resource, ResourceHandle } from './utility-types';
+export type { default as ResourceControls } from './resource-controls';

package/src/inherited-context.ts

@@ -0,0 +1,32 @@
+/**
+ * A prototype chain that matches the resource hierarchy. This is used to
+ * pass state down the tree without plumbing through every function.
+ */
+export type InheritedContext = Record<symbol, unknown>;
+
+/** An opaque handle used to get/set values in a prototype chain. */
+export class ContextHandle<Value> {
+  static getId(handle: ContextHandle<unknown>): symbol {
+    return handle.#id;
+  }
+
+  static getDefaultValue<Value>(handle: ContextHandle<Value>): Value {
+    return handle.#getDefaultContext();
+  }
+
+  #id = Symbol('Context ID');
+  #getDefaultContext: () => Value;
+
+  constructor(getDefaultContext: () => Value) {
+    this.#getDefaultContext = getDefaultContext;
+  }
+}
+
+/**
+ * Create a context object that is used to get and set context values in the
+ * resource hierarchy.
+ */
+export const createContext = <Value>(
+  /** Returns a default value if the context could not be found. */
+  getDefaultContext: () => Value,
+): ContextHandle<Value> => new ContextHandle(getDefaultContext);

package/src/{resource-context.ts → resource-controls.ts}

@@ -1,23 +1,27 @@
-import { create, destroy } from './allocation';
-import { RevokableResource } from './state';
-import { ResourceFactory, ParametrizedResourceFactory } from './types';
+import { createWithContext, destroy } from './resource-lifecycle';
+import { ContextHandle, InheritedContext } from './inherited-context';
+import { RevokableResource } from './global-weakrefs';
+import { ResourceFactory, ParametrizedResourceFactory } from './utility-types';
 
 /**
  * An instance of this class is passed to resources as they're being
  * provisioned. It allows them to provision other resources while keeping
  * track of ownership and lifetimes.
  */
-export default class ResourceContext {
+export default class ResourceControls {
   #destroyed = new WeakSet<object>();
   #resources: Set<object>;
-  #freeze: RevokableResource['curfew'];
+  #curfew: RevokableResource['curfew'];
+  #state: InheritedContext;
 
   constructor(
+    state: InheritedContext,
     ownedResources: Set<object>,
     freeze: RevokableResource['curfew'],
   ) {
+    this.#state = state;
     this.#resources = ownedResources;
-    this.#freeze = freeze;
+    this.#curfew = freeze;
   }
 
   /** Provision an owned resource and make sure it doesn't outlive us. */
@@ -27,11 +31,12 @@ export default class ResourceContext {
       | ResourceFactory<Controls>,
     ...args: Args
   ): Promise<Controls> => {
-    if (this.#freeze.enforced) {
+    if (this.#curfew.enforced) {
       throw new Error('Cannot create new resources after teardown.');
     }
 
-    const controls = await create(factory, ...args);
+    const context = Object.create(this.#state);
+    const controls = await createWithContext(context, factory, ...args);
     this.#resources.add(controls);
 
     return controls;
@@ -54,4 +59,23 @@ export default class ResourceContext {
     this.#destroyed.add(resource);
     await destroy(resource);
   };
+
+  /** Store a value in context. Anything down the chain can read it. */
+  public setContext = <Value>(
+    context: ContextHandle<Value>,
+    value: Value,
+  ): void => {
+    this.#state[ContextHandle.getId(context)] = value;
+  };
+
+  /** Retrieve a value from context, or a default if it is unset. */
+  public getContext = <Value>(context: ContextHandle<Value>): Value => {
+    const id = ContextHandle.getId(context);
+
+    if (id in this.#state) {
+      return this.#state[id] as Value;
+    }
+
+    return ContextHandle.getDefaultValue(context);
+  };
 }

package/src/{allocation.ts → resource-lifecycle.ts}

@@ -1,25 +1,27 @@
-import { resources, constructed } from './state';
-import wrap from './proxy';
-import ResourceContext from './resource-context';
-import { ResourceFactory, ParametrizedResourceFactory } from './types';
+import { resources, constructed } from './global-weakrefs';
+import wrap from './wrap-with-proxy';
+import ResourceControls from './resource-controls';
+import type { InheritedContext } from './inherited-context';
+import { ResourceFactory, ParametrizedResourceFactory } from './utility-types';
 
 /** Provision a resource and return its external API. */
-export const create = async <
+export const createWithContext = async <
   Controls extends object,
   Args extends Array<unknown>,
 >(
-  provision:
+  state: InheritedContext,
+  factory:
     | ParametrizedResourceFactory<Controls, Args>
     | ResourceFactory<Controls>,
   ...args: Args
 ): Promise<Controls> => {
   const curfew = { enforced: false };
   const children: Set<object> = new Set();
-  const context = new ResourceContext(children, curfew);
-  let resource: Awaited<ReturnType<typeof provision>>;
+  const context = new ResourceControls(state, children, curfew);
+  let resource: Awaited<ReturnType<typeof factory>>;
 
   try {
-    resource = await provision(context, ...args);
+    resource = await factory(context, ...args);
   } catch (error) {
     // Resource could not be created. Clean up the intermediate resources.
     const orphans = Array.from(children).reverse();

package/src/root-lifecycle.ts

@@ -0,0 +1,22 @@
+import { createWithContext } from './resource-lifecycle';
+import { ParametrizedResourceFactory } from './utility-types';
+import { ResourceFactory } from './utility-types';
+
+/** Provision a resource and return its external API. */
+export const create = async <
+  Controls extends object,
+  Args extends Array<unknown>,
+>(
+  /** An async function that resolves to a resource. */
+  factory:
+    | ParametrizedResourceFactory<Controls, Args>
+    | ResourceFactory<Controls>,
+  ...args: Args
+): Promise<Controls> => {
+  const rootContext = Object.create(null);
+  return createWithContext(rootContext, factory, ...args);
+};
+
+// Destroying a root resource is the same process as destroying a child
+// resource. No need to change the implementation.
+export { destroy } from './resource-lifecycle';