wardens 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [0.3.0] - 2022-06-04
+
+### Changed
+
+- Prevent use of `allocate(...)`/`deallocate(...)` outside a resource subclass.
+- Renamed `enter()` and `leave()` to `create()` and `destroy()`.
+- Renamed `mount()` and `unmount()` to `create()` and `destroy()`.
+
+### Removed
+
+- Second type parameter to `Resource` is gone. Arguments to `enter(...)` are now inferred.
+- No more default implementations for `enter(...)`/`leave(...)` on resources.
+
 ## [0.2.0] - 2022-05-24
 
 ### Fixed
@@ -29,6 +42,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - `mount`/`unmount` hooks to provision resources
 - `allocate`/`deallocate` for creating hierarchies of resources
 
-[Unreleased]: https://github.com/PsychoLlama/wardens/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/PsychoLlama/wardens/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/PsychoLlama/wardens/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/PsychoLlama/wardens/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/PsychoLlama/wardens/releases/tag/v0.1.0

package/README.md

@@ -17,12 +17,12 @@ class Worker extends Resource<Thread> {
   thread!: Thread;
 
   // Called when the resource is created
-  async enter() {
+  async create() {
     this.thread = await spawn()
   }
 
   // Called when the resource is destroyed
-  async leave() {
+  async destroy() {
     this.thread.close()
   }
 
@@ -34,11 +34,11 @@ class Worker extends Resource<Thread> {
 Now define a pool that creates and manages workers:
 
 ```typescript
-class WorkerPool extends Resource<Controls, [Config]> {
+class WorkerPool extends Resource<Controls> {
   threads!: Array<Thread> = [];
 
-  async enter({ poolSize }: Config) {
-    const promises = Array(poolSize).fill().map(() => {
+  async create({ poolSize }: Config) {
+    const promises = Array.from({ length: poolSize }, () => {
       return this.allocate(Worker)
     })
 
@@ -53,10 +53,10 @@ class WorkerPool extends Resource<Controls, [Config]> {
 }
 ```
 
-Finally, mount it:
+Finally, create the pool:
 
 ```typescript
-const pool = await mount(WorkerPool, {
+const pool = await create(WorkerPool, {
   poolSize: cpus().length,
 })
 
@@ -68,7 +68,7 @@ pool.doSomethingElse()
 The magic of this framework is that resources never outlive their owners. If you tear down the pool, it will deallocate everything beneath it first:
 
 ```typescript
-await unmount(pool)
+await destroy(pool)
 
 // [info] closing worker
 // [info] closing worker

package/dist/wardens.es.js

@@ -17,9 +17,11 @@ const ownership = /* @__PURE__ */ new WeakMap();
 function wrapWithProxy(value) {
   return Proxy.revocable(value, {});
 }
-async function mount(Entity, ...args) {
+async function create(Entity, ...args) {
   const resource = new Entity();
-  await resource.enter(...args);
+  if (mountable(resource)) {
+    await resource.create(...args);
+  }
   const controls = resource.exports();
   const { proxy, revoke } = wrapWithProxy(controls);
   resources.set(proxy, {
@@ -28,16 +30,18 @@ async function mount(Entity, ...args) {
   });
   return proxy;
 }
-async function unmount(controls) {
+async function destroy(controls) {
   const entry = resources.get(controls);
   if (entry) {
     resources.delete(controls);
     entry.revoke();
     const children = ownership.get(entry.resource);
     ownership.delete(entry.resource);
-    const recursiveUnmounts = children.map((controls2) => unmount(controls2));
+    const recursiveUnmounts = children.map((controls2) => destroy(controls2));
     const results = await Promise.allSettled(recursiveUnmounts);
-    await entry.resource.leave();
+    if (unmountable(entry.resource)) {
+      await entry.resource.destroy();
+    }
     results.forEach((result) => {
       if (result.status === "rejected") {
         throw result.reason;
@@ -45,20 +49,20 @@ async function unmount(controls) {
     });
   }
 }
+function mountable(resource) {
+  return "create" in resource;
+}
+function unmountable(resource) {
+  return "destroy" in resource;
+}
 class Resource {
   constructor() {
     __privateAdd(this, _resources, /* @__PURE__ */ new WeakSet());
     __privateAdd(this, _children, []);
     ownership.set(this, __privateGet(this, _children));
   }
-  async enter(..._args) {
-    return;
-  }
-  async leave() {
-    return;
-  }
   async allocate(Child, ...args) {
-    const controls = await mount(Child, ...args);
+    const controls = await create(Child, ...args);
     __privateGet(this, _resources).add(controls);
     __privateGet(this, _children).push(controls);
     return controls;
@@ -67,7 +71,7 @@ class Resource {
     if (!__privateGet(this, _resources).has(resource)) {
       throw new Error("You do not own this resource.");
     }
-    return unmount(resource);
+    return destroy(resource);
   }
 }
 _resources = new WeakMap();
@@ -92,4 +96,4 @@ function bindContext(value) {
     }
   });
 }
-export { Resource, bindContext, mount, unmount };
+export { Resource, bindContext, create, destroy };

package/dist/wardens.umd.js

@@ -1 +1 @@
-var b=(e,t,c)=>{if(!t.has(e))throw TypeError("Cannot "+c)};var f=(e,t,c)=>(b(e,t,"read from private field"),c?c.call(e):t.get(e)),h=(e,t,c)=>{if(t.has(e))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(e):t.set(e,c)};(function(e,t){typeof exports=="object"&&typeof module!="undefined"?t(exports):typeof define=="function"&&define.amd?define(["exports"],t):(e=typeof globalThis!="undefined"?globalThis:e||self,t(e.wardens={}))})(this,function(e){var a,d;"use strict";const t=new WeakMap,c=new WeakMap;function p(i){return Proxy.revocable(i,{})}async function w(i,...n){const o=new i;await o.enter(...n);const s=o.exports(),{proxy:r,revoke:u}=p(s);return t.set(r,{resource:o,revoke:u}),r}async function l(i){const n=t.get(i);if(n){t.delete(i),n.revoke();const o=c.get(n.resource);c.delete(n.resource);const s=o.map(u=>l(u)),r=await Promise.allSettled(s);await n.resource.leave(),r.forEach(u=>{if(u.status==="rejected")throw u.reason})}}class y{constructor(){h(this,a,new WeakSet);h(this,d,[]);c.set(this,f(this,d))}async enter(...n){}async leave(){}async allocate(n,...o){const s=await w(n,...o);return f(this,a).add(s),f(this,d).push(s),s}async deallocate(n){if(!f(this,a).has(n))throw new Error("You do not own this resource.");return l(n)}}a=new WeakMap,d=new WeakMap;function m(i){const n=new WeakMap;return new Proxy(i,{get(o,s){const r=Reflect.get(o,s,o);if(typeof r=="function"){if(n.has(r)===!1){const u=r.bind(o);Object.defineProperties(u,Object.getOwnPropertyDescriptors(r)),n.set(r,u)}return n.get(r)}return r},set(o,s,r){return Reflect.set(o,s,r,o)}})}e.Resource=y,e.bindContext=m,e.mount=w,e.unmount=l,Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});
+var v=(e,t,i)=>{if(!t.has(e))throw TypeError("Cannot "+i)};var f=(e,t,i)=>(v(e,t,"read from private field"),i?i.call(e):t.get(e)),h=(e,t,i)=>{if(t.has(e))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(e):t.set(e,i)};(function(e,t){typeof exports=="object"&&typeof module!="undefined"?t(exports):typeof define=="function"&&define.amd?define(["exports"],t):(e=typeof globalThis!="undefined"?globalThis:e||self,t(e.wardens={}))})(this,function(e){var a,d;"use strict";const t=new WeakMap,i=new WeakMap;function y(s){return Proxy.revocable(s,{})}async function w(s,...n){const o=new s;p(o)&&await o.create(...n);const c=o.exports(),{proxy:r,revoke:u}=y(c);return t.set(r,{resource:o,revoke:u}),r}async function l(s){const n=t.get(s);if(n){t.delete(s),n.revoke();const o=i.get(n.resource);i.delete(n.resource);const c=o.map(u=>l(u)),r=await Promise.allSettled(c);b(n.resource)&&await n.resource.destroy(),r.forEach(u=>{if(u.status==="rejected")throw u.reason})}}function p(s){return"create"in s}function b(s){return"destroy"in s}class m{constructor(){h(this,a,new WeakSet);h(this,d,[]);i.set(this,f(this,d))}async allocate(n,...o){const c=await w(n,...o);return f(this,a).add(c),f(this,d).push(c),c}async deallocate(n){if(!f(this,a).has(n))throw new Error("You do not own this resource.");return l(n)}}a=new WeakMap,d=new WeakMap;function g(s){const n=new WeakMap;return new Proxy(s,{get(o,c){const r=Reflect.get(o,c,o);if(typeof r=="function"){if(n.has(r)===!1){const u=r.bind(o);Object.defineProperties(u,Object.getOwnPropertyDescriptors(r)),n.set(r,u)}return n.get(r)}return r},set(o,c,r){return Reflect.set(o,c,r,o)}})}e.Resource=m,e.bindContext=g,e.create=w,e.destroy=l,Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardens",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A framework for resource management",
   "main": "./dist/wardens.umd.js",
   "module": "./dist/wardens.es.js",
@@ -82,16 +82,16 @@
     "preset": "ts-jest"
   },
   "devDependencies": {
-    "@types/jest": "27.5.1",
-    "@typescript-eslint/eslint-plugin": "5.26.0",
-    "@typescript-eslint/parser": "5.26.0",
-    "eslint": "8.16.0",
+    "@types/jest": "28.1.0",
+    "@typescript-eslint/eslint-plugin": "5.27.0",
+    "@typescript-eslint/parser": "5.27.0",
+    "eslint": "8.17.0",
     "husky": "8.0.1",
     "jest": "28.1.0",
-    "lint-staged": "12.4.1",
+    "lint-staged": "13.0.0",
     "prettier": "2.6.2",
-    "ts-jest": "28.0.3",
-    "typescript": "4.6.4",
+    "ts-jest": "28.0.4",
+    "typescript": "4.7.3",
     "vite": "2.9.9",
     "vite-dts": "1.0.4"
   }

package/src/__tests__/allocation.test.ts

@@ -1,36 +1,38 @@
 import Resource from '../resource';
-import { mount, unmount } from '../allocation';
+import { create, destroy } from '../allocation';
 
 describe('allocation', () => {
-  describe('mount', () => {
+  describe('create', () => {
     it('allocates the resource', async () => {
       const config = { test: 'init-args' };
-      const enter = jest.fn();
+      const spy = jest.fn((config: { test: string }) => {
+        config;
+      });
 
-      class Test extends Resource<{ test: boolean }, [{ test: string }]> {
+      class Test extends Resource<{ test: boolean }> {
         exports = () => ({ test: true });
-        enter = enter;
+        create = spy;
       }
 
-      await expect(mount(Test, config)).resolves.toEqual({ test: true });
-      expect(enter).toHaveBeenCalledWith(config);
+      await expect(create(Test, config)).resolves.toEqual({ test: true });
+      expect(spy).toHaveBeenCalledWith(config);
     });
   });
 
-  describe('unmount', () => {
+  describe('destroy', () => {
     it('deallocates the resource', async () => {
-      const leave = jest.fn();
+      const spy = jest.fn<void, []>();
 
       class Test extends Resource<Array<string>> {
         exports = () => [];
-        leave = leave;
+        destroy = spy;
       }
 
-      const test = await mount(Test);
+      const test = await create(Test);
 
-      expect(leave).not.toHaveBeenCalled();
-      await expect(unmount(test)).resolves.not.toThrow();
-      expect(leave).toHaveBeenCalled();
+      expect(spy).not.toHaveBeenCalled();
+      await expect(destroy(test)).resolves.not.toThrow();
+      expect(spy).toHaveBeenCalled();
     });
 
     it('survives if the resource is already deallocated', async () => {
@@ -38,50 +40,50 @@ describe('allocation', () => {
         exports = () => [];
       }
 
-      const test = await mount(Test);
-      await unmount(test);
+      const test = await create(Test);
+      await destroy(test);
 
-      await expect(unmount(test)).resolves.not.toThrow();
+      await expect(destroy(test)).resolves.not.toThrow();
     });
 
     it('automatically unmounts all children', async () => {
-      const leave = jest.fn();
+      const spy = jest.fn();
       class Child extends Resource<number[]> {
         exports = () => [];
-        leave = leave;
+        destroy = spy;
       }
 
       class Parent extends Resource<string[]> {
         exports = () => [];
-        async enter() {
+        async create() {
           await this.allocate(Child);
         }
       }
 
-      const parent = await mount(Parent);
-      await unmount(parent);
+      const parent = await create(Parent);
+      await destroy(parent);
 
-      expect(leave).toHaveBeenCalled();
+      expect(spy).toHaveBeenCalled();
     });
 
-    it('throws an error if any of the children fail to unmount', async () => {
-      const error = new Error('Testing unmount errors');
+    it('throws an error if any of the children fail to close', async () => {
+      const error = new Error('Testing resource destruction errors');
       class Child extends Resource<number[]> {
         exports = () => [];
-        async leave() {
+        async destroy() {
           throw error;
         }
       }
 
       class Parent extends Resource<string[]> {
         exports = () => [];
-        async enter() {
+        async create() {
           await this.allocate(Child);
         }
       }
 
-      const parent = await mount(Parent);
-      await expect(unmount(parent)).rejects.toThrow(error);
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toThrow(error);
     });
   });
 });

package/src/__tests__/resource.test.ts

@@ -1,19 +1,12 @@
 import Resource from '../resource';
-import { mount } from '../allocation';
-import { type Controls } from '../types';
+import { create } from '../allocation';
+import { Controls } from '../types';
 
 describe('Resource', () => {
   class Test extends Resource<Record<string, never>> {
     exports = () => ({});
   }
 
-  it('implements default enter/leave methods', async () => {
-    const test = new Test();
-
-    await expect(test.enter()).resolves.not.toThrow();
-    await expect(test.leave()).resolves.not.toThrow();
-  });
-
   it('can spawn children of its own', async () => {
     class Child extends Resource<{ child: boolean }> {
       exports = () => ({ child: true });
@@ -23,46 +16,46 @@ describe('Resource', () => {
       exports = () => this.child;
       child!: Controls<Child>;
 
-      async enter() {
+      async create() {
         this.child = await this.allocate(Child);
       }
     }
 
-    await expect(mount(Parent)).resolves.toEqual({ child: true });
+    await expect(create(Parent)).resolves.toEqual({ child: true });
   });
 
   it('can deallocate child resources on demand', async () => {
-    const leave = jest.fn();
+    const spy = jest.fn();
 
     class Child extends Resource<{ child: boolean }> {
       exports = () => ({ child: true });
-      leave = leave;
+      destroy = spy;
     }
 
     class Parent extends Resource<{ parent: boolean }> {
       exports = () => ({ parent: true });
       child!: Controls<Child>;
 
-      async enter() {
+      async create() {
         const child = await this.allocate(Child);
         await this.deallocate(child);
       }
     }
 
-    await expect(mount(Parent)).resolves.toEqual({ parent: true });
-    expect(leave).toHaveBeenCalled();
+    await expect(create(Parent)).resolves.toEqual({ parent: true });
+    expect(spy).toHaveBeenCalled();
   });
 
   it('fails to destroy resources owned by someone else', async () => {
-    const test = await mount(Test);
+    const test = await create(Test);
 
     class Sneaky extends Resource<string[]> {
       exports = () => [];
-      async enter() {
+      async create() {
         await this.deallocate(test);
       }
     }
 
-    await expect(mount(Sneaky)).rejects.toThrow(/do not own/i);
+    await expect(create(Sneaky)).rejects.toThrow(/do not own/i);
   });
 });

package/src/allocation.ts

@@ -1,17 +1,21 @@
 import type Resource from './resource';
 import { resources, ownership } from './state';
 import wrap from './proxy';
+import { MountableResource, UnmountableResource } from './types';
 
 /** Provision a resource and return its external API. */
-export async function mount<
+export async function create<
   Controls extends object,
   Args extends Array<unknown>,
 >(
-  Entity: new () => Resource<Controls, Args>,
+  Entity: new () => MountableResource<Controls, Args> | Resource<Controls>,
   ...args: Args
 ): Promise<Controls> {
   const resource = new Entity();
-  await resource.enter(...args);
+
+  if (mountable(resource)) {
+    await resource.create(...args);
+  }
 
   const controls = resource.exports();
   const { proxy, revoke } = wrap(controls);
@@ -30,7 +34,7 @@ export async function mount<
  *
  * @todo Add type marker to catch cases where the wrong object is unmounted.
  */
-export async function unmount(controls: object) {
+export async function destroy(controls: object) {
   const entry = resources.get(controls);
 
   if (entry) {
@@ -44,11 +48,13 @@ export async function unmount(controls: object) {
     ownership.delete(entry.resource);
 
     // Recursively close out the children first...
-    const recursiveUnmounts = children.map((controls) => unmount(controls));
+    const recursiveUnmounts = children.map((controls) => destroy(controls));
     const results = await Promise.allSettled(recursiveUnmounts);
 
     // Then close the parent.
-    await entry.resource.leave();
+    if (unmountable(entry.resource)) {
+      await entry.resource.destroy();
+    }
 
     // Fail loudly if any of the children couldn't be deallocated.
     results.forEach((result) => {
@@ -58,3 +64,15 @@ export async function unmount(controls: object) {
     });
   }
 }
+
+function mountable(
+  resource: MountableResource<object, Array<unknown>> | Resource<object>,
+): resource is MountableResource<object, Array<unknown>> {
+  return 'create' in resource;
+}
+
+function unmountable(
+  resource: UnmountableResource<object> | Resource<object>,
+): resource is UnmountableResource<object> {
+  return 'destroy' in resource;
+}

package/src/index.ts

@@ -1,4 +1,4 @@
 export { default as Resource } from './resource';
 export { default as bindContext } from './bind-context';
-export { mount, unmount } from './allocation';
+export { create, destroy } from './allocation';
 export type { Controls } from './types';

package/src/resource.ts

@@ -1,15 +1,13 @@
-import { mount, unmount } from './allocation';
+import { create, destroy } from './allocation';
 import { ownership } from './state';
+import { MountableResource } from './types';
 
 /**
  * Represents an arbitrary stateful resource that is asynchronously provisioned
  * and destroyed. Resources can own other resources, and destroying a parent
  * first tears down the children.
  */
-export default abstract class Resource<
-  Controls extends object,
-  Args extends Array<unknown> = [],
-> {
+export default abstract class Resource<Controls extends object> {
   #resources = new WeakSet<object>();
   #children: Array<object> = [];
 
@@ -17,26 +15,17 @@ export default abstract class Resource<
     ownership.set(this, this.#children);
   }
 
-  /** A hook that gets called when the resource is created. */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async enter(..._args: Args) {
-    return;
-  }
-
-  /** A hook that gets called when the resource is destroyed. */
-  async leave() {
-    return;
-  }
-
   /** Provision an owned resource and make sure it doesn't outlive us. */
-  async allocate<
+  protected async allocate<
     ChildControls extends object,
-    ChildArgs extends Array<unknown> = [],
+    ChildArgs extends Array<unknown>,
   >(
-    Child: new () => Resource<ChildControls, ChildArgs>,
+    Child: new () =>
+      | MountableResource<ChildControls, ChildArgs>
+      | Resource<ChildControls>,
     ...args: ChildArgs
   ): Promise<ChildControls> {
-    const controls = await mount(Child, ...args);
+    const controls: ChildControls = await create(Child, ...args);
     this.#resources.add(controls);
     this.#children.push(controls);
 
@@ -47,12 +36,12 @@ export default abstract class Resource<
    * Tear down a resource. Happens automatically when resource owners are
    * deallocated.
    */
-  async deallocate(resource: object) {
+  protected async deallocate(resource: object) {
     if (!this.#resources.has(resource)) {
       throw new Error('You do not own this resource.');
     }
 
-    return unmount(resource);
+    return destroy(resource);
   }
 
   /** Returns an external API to the parent resource. */

package/src/state.ts

@@ -1,7 +1,7 @@
 import type Resource from './resource';
 
 interface RevokableResource {
-  resource: Resource<object, Array<unknown>>;
+  resource: Resource<object>;
 
   /**
    * Destroys outer references to the API and frees the object for garbage
@@ -14,7 +14,4 @@ interface RevokableResource {
 export const resources = new WeakMap<object, RevokableResource>();
 
 /** Maps a resource to all the other resources it provisioned. */
-export const ownership = new WeakMap<
-  Resource<object, Array<unknown>>,
-  Array<object>
->();
+export const ownership = new WeakMap<Resource<object>, Array<object>>();

package/src/types.ts

@@ -1,8 +1,19 @@
 import type Resource from './resource';
 
 /** The `exports` type for a resource. */
-export type Controls<
-  ArbitraryResource extends Resource<object, Array<unknown>>,
-> = ArbitraryResource extends Resource<infer Controls, Array<unknown>>
-  ? Controls
-  : never;
+export type Controls<ArbitraryResource extends Resource<object>> =
+  ArbitraryResource extends Resource<infer Controls> ? Controls : never;
+
+export interface MountableResource<
+  Controls extends object,
+  InitArgs extends Array<unknown>,
+> extends Resource<Controls> {
+  /** A hook that gets called when the resource is created. */
+  create(...args: InitArgs): Promise<void>;
+}
+
+export interface UnmountableResource<Controls extends object>
+  extends Resource<Controls> {
+  /** A hook that gets called when the resource is destroyed. */
+  destroy(): Promise<void>;
+}