wardens 0.5.0-rc.0 → 0.5.1-2024-07-28.65ce2a7

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

@@ -0,0 +1,249 @@
+import type ResourceScope from '../resource-scope';
+import { create, destroy } from '../';
+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: ResourceScope, 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: ResourceScope) => {
+          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: ResourceScope) => {
+          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: ResourceScope) {
+        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: ResourceScope) => {
+        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: ResourceScope) => {
+        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: ResourceScope) => {
+        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: ResourceScope) => {
+        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: ResourceScope) => {
+        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: ResourceScope) => {
+        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: ResourceScope) => ({
+        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,
+      );
+    });
+
+    it('refuses to destroy non-root resources', async () => {
+      const Child = async () => ({ value: [] });
+      const Parent = async ({ create }: ResourceScope) => ({
+        value: { child: await create(Child) },
+      });
+
+      const { child } = await create(Parent);
+
+      await expect(destroy(child)).rejects.toThrow(
+        /cannot destroy child resource/i,
+      );
+    });
+  });
+});

package/src/__tests__/{allocation.test.ts → roots.test.ts}

@@ -1,13 +1,13 @@
-import type ResourceContext from '../resource-context';
-import { create, destroy } from '../allocation';
+import type ResourceScope from '../resource-scope';
+import { create, destroy } from '../';
 import bindContext from '../bind-context';
 
-describe('allocation', () => {
+describe('roots', () => {
   describe('create', () => {
     it('allocates the resource', async () => {
       const config = { test: 'init-args' };
       const Test = vi.fn(
-        async (_resource: ResourceContext, config: { test: string }) => ({
+        async (_resource: ResourceScope, config: { test: string }) => ({
           value: config,
         }),
       );
@@ -22,7 +22,7 @@ describe('allocation', () => {
         const First = async () => ({ value: [], destroy: () => spy('1st') });
         const Second = async () => ({ value: [], destroy: () => spy('2nd') });
 
-        const Parent = async (resource: ResourceContext) => {
+        const Parent = async (resource: ResourceScope) => {
           await resource.create(First);
           await resource.create(Second);
           throw new Error('Testing resource initialization errors');
@@ -42,7 +42,7 @@ describe('allocation', () => {
           },
         });
 
-        const Parent = async (resource: ResourceContext) => {
+        const Parent = async (resource: ResourceScope) => {
           await resource.create(Child);
           await resource.create(Child);
           throw parentError;
@@ -58,7 +58,7 @@ describe('allocation', () => {
 
   describe('destroy', () => {
     it('deallocates the resource', async () => {
-      const spy = vi.fn<[], void>();
+      const spy = vi.fn<() => void>();
       const Test = async () => ({
         value: {},
         destroy: spy,
@@ -89,7 +89,7 @@ describe('allocation', () => {
     it('automatically unmounts all children', async () => {
       const spy = vi.fn();
       const Child = async () => ({ value: [], destroy: spy });
-      async function Parent(resource: ResourceContext) {
+      async function Parent(resource: ResourceScope) {
         await resource.create(Child);
         return { value: [] };
       }
@@ -109,7 +109,7 @@ describe('allocation', () => {
         },
       });
 
-      const Parent = async (resource: ResourceContext) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return { value: [] };
       };
@@ -123,7 +123,7 @@ describe('allocation', () => {
       const First = async () => ({ value: [], destroy: () => spy('1st') });
       const Second = async () => ({ value: [], destroy: () => spy('2nd') });
 
-      const Parent = async (resource: ResourceContext) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(First);
         await resource.create(Second);
         return { value: [] };
@@ -144,7 +144,7 @@ describe('allocation', () => {
         },
       });
 
-      const Parent = async (resource: ResourceContext) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         await resource.create(Child);
         return { value: [] };
@@ -158,7 +158,7 @@ describe('allocation', () => {
 
     it('ensures child resources outlive their consumers', async () => {
       const Child = async () => ({ value: [1] });
-      const Parent = async (resource: ResourceContext) => {
+      const Parent = async (resource: ResourceScope) => {
         const child = await resource.create(Child);
         return {
           value: [],
@@ -176,7 +176,7 @@ describe('allocation', () => {
     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: ResourceContext) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return {
           value: [],
@@ -202,7 +202,7 @@ describe('allocation', () => {
         },
       });
 
-      const Parent = async (resource: ResourceContext) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return {
           value: [],
@@ -220,7 +220,7 @@ describe('allocation', () => {
 
     it('guards against creating new resources after teardown', async () => {
       const Child = async () => ({ value: [] });
-      const Parent = async (resource: ResourceContext) => ({
+      const Parent = async (resource: ResourceScope) => ({
         value: bindContext(resource),
       });
 

package/src/__tests__/utility-types.test-d.ts

@@ -0,0 +1,56 @@
+import {
+  create,
+  ResourceScope,
+  ResourceHandle,
+  createContext,
+  ContextType,
+} from '../';
+
+describe('Utility types', () => {
+  describe('ResourceHandle', () => {
+    it('infers the correct type', async () => {
+      async function Test() {
+        return {
+          value: { hello: 'world' },
+        };
+      }
+
+      const test = await create(Test);
+
+      expectTypeOf(test).toEqualTypeOf<ResourceHandle<typeof Test>>({
+        hello: 'world',
+      });
+    });
+
+    it('infers the type when the value comes from a parameter', async () => {
+      async function Test(_ctx: ResourceScope, value: { count: number }) {
+        return {
+          value,
+        };
+      }
+
+      const test = await create(Test, { count: 2 });
+      expectTypeOf(test).toEqualTypeOf<ResourceHandle<typeof Test>>({
+        count: 2,
+      });
+    });
+  });
+
+  describe('ContextType', () => {
+    it('returns the type contained in context', async () => {
+      const Context = createContext(() => ({
+        hello: 'world',
+      }));
+
+      async function Test({ getContext }: ResourceScope) {
+        return { value: getContext(Context) };
+      }
+
+      const value = await create(Test);
+
+      expectTypeOf(value).toEqualTypeOf<ContextType<typeof Context>>({
+        hello: 'any string, really',
+      });
+    });
+  });
+});

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

@@ -1,4 +1,20 @@
-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>();
+
+/**
+ * Indicates if an object is a root resource. This is used to prevent
+ * child resources from being destroyed by the root `destroy(...)` function.
+ */
+export const roots = new WeakSet<object>();
 
 export interface RevokableResource {
   resource: Resource<object>;
@@ -18,13 +34,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 { createRoot as create, destroyRoot as destroy } from './root-lifecycle';
+export { createContext } from './inherited-context';
+export type { Resource, ResourceHandle, ContextType } from './utility-types';
+export type { default as ResourceScope } from './resource-scope';

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/{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 ResourceScope from './resource-scope';
+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 ResourceScope(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();
@@ -58,7 +60,7 @@ export const create = async <
 
 /**
  * Tear down the resource and all its children, permanently destroying the
- * reference.
+ * reference. This works on both root resources and child resources.
  */
 export const destroy = async (handle: object) => {
   if (!constructed.has(handle)) {
@@ -117,7 +119,10 @@ const reduceToSingleError = (errors: Array<Error>, options?: ErrorOptions) => {
 
 /** Happens when 2 or more child resources cannot be destroyed. */
 class BulkDestroyError extends Error {
-  constructor(public failures: Array<unknown>, options?: ErrorOptions) {
+  constructor(
+    public failures: Array<unknown>,
+    options?: ErrorOptions,
+  ) {
     super(
       'Some resources could not be destroyed. See the `failures` property for details.',
       options,

package/src/{resource-context.ts → resource-scope.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 ResourceScope {
   #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,24 @@ 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,
+  ): Value => {
+    this.#state[ContextHandle.getId(context)] = value;
+    return 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/root-lifecycle.ts

@@ -0,0 +1,36 @@
+import { createWithContext, destroy } from './resource-lifecycle';
+import { ParametrizedResourceFactory } from './utility-types';
+import { ResourceFactory } from './utility-types';
+import { resources, roots } from './global-weakrefs';
+
+/** Provision a resource and return its external API. */
+export const createRoot = 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);
+  const root = await createWithContext(rootContext, factory, ...args);
+  roots.add(root);
+
+  return root;
+};
+
+/**
+ * Tear down the resource and all its children, permanently destroying the
+ * reference. This cannot be used to destroy child resources, only roots.
+ */
+export const destroyRoot = async (resource: object): Promise<void> => {
+  if (resources.has(resource) && !roots.has(resource)) {
+    throw new Error(
+      'Cannot destroy child resource. It is owned by another scope.',
+    );
+  }
+
+  return destroy(resource);
+};