wardens 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,7 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
-## [0.1.0]
+## [0.2.0] - 2022-05-24
+
+### Fixed
+
+- `mount(...)` and `allocate(...)` no longer require a config argument if the resource doesn't explicitly define one.
+
+### Added
+
+- `enter(...)` now supports variable arguments.
+
+### Changed
+
+- The second generic parameter of `Resource` was a config parameter, but now it's an argument tuple.
+- The `ExternalControls` utility type was renamed to `Controls`.
+
+## [0.1.0] - 2022-05-22
 
 ### Added
 
@@ -14,5 +29,6 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/PsychoLlama/wardens/compare/v0.2.0...HEAD
+[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

@@ -1,6 +1,10 @@
-# Wardens
-
-A tiny framework for managing resources.
+<div align="center">
+  <h1>Wardens</h1>
+  <p>A tiny framework for managing resources.</p>
+  <img alt="Build status" src="https://img.shields.io/github/workflow/status/PsychoLlama/wardens/Test/main" />
+  <img alt="TypeScript" src="https://img.shields.io/npm/types/wardens" />
+  <img alt="npm version" src="https://img.shields.io/npm/v/wardens" />
+</div>
 
 ## Overview
 
@@ -30,7 +34,7 @@ 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, [Config]> {
   threads!: Array<Thread> = [];
 
   async enter({ poolSize }: Config) {

package/dist/wardens.es.js

@@ -17,25 +17,25 @@ const ownership = /* @__PURE__ */ new WeakMap();
 function wrapWithProxy(value) {
   return Proxy.revocable(value, {});
 }
-async function mount(Subtype, params) {
-  const resource = new Subtype();
-  await resource.enter(params);
-  const api = resource.exports();
-  const { proxy, revoke } = wrapWithProxy(api);
+async function mount(Entity, ...args) {
+  const resource = new Entity();
+  await resource.enter(...args);
+  const controls = resource.exports();
+  const { proxy, revoke } = wrapWithProxy(controls);
   resources.set(proxy, {
     resource,
     revoke
   });
   return proxy;
 }
-async function unmount(api) {
-  const entry = resources.get(api);
+async function unmount(controls) {
+  const entry = resources.get(controls);
   if (entry) {
-    resources.delete(api);
+    resources.delete(controls);
     entry.revoke();
     const children = ownership.get(entry.resource);
     ownership.delete(entry.resource);
-    const recursiveUnmounts = children.map((api2) => unmount(api2));
+    const recursiveUnmounts = children.map((controls2) => unmount(controls2));
     const results = await Promise.allSettled(recursiveUnmounts);
     await entry.resource.leave();
     results.forEach((result) => {
@@ -51,23 +51,23 @@ class Resource {
     __privateAdd(this, _children, []);
     ownership.set(this, __privateGet(this, _children));
   }
-  async enter(_params) {
+  async enter(..._args) {
     return;
   }
   async leave() {
     return;
   }
-  async allocate(Child, params) {
-    const api = await mount(Child, params);
-    __privateGet(this, _resources).add(api);
-    __privateGet(this, _children).push(api);
-    return api;
+  async allocate(Child, ...args) {
+    const controls = await mount(Child, ...args);
+    __privateGet(this, _resources).add(controls);
+    __privateGet(this, _children).push(controls);
+    return controls;
   }
-  async deallocate(api) {
-    if (!__privateGet(this, _resources).has(api)) {
+  async deallocate(resource) {
+    if (!__privateGet(this, _resources).has(resource)) {
       throw new Error("You do not own this resource.");
     }
-    return unmount(api);
+    return unmount(resource);
   }
 }
 _resources = new WeakMap();

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 w(i){return Proxy.revocable(i,{})}async function p(i,n){const o=new i;await o.enter(n);const s=o.exports(),{proxy:r,revoke:u}=w(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 p(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=p,e.unmount=l,Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});
+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"}})});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardens",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A framework for resource management",
   "main": "./dist/wardens.umd.js",
   "module": "./dist/wardens.es.js",
@@ -11,6 +11,15 @@
     "dist",
     "src"
   ],
+  "keywords": [
+    "resource",
+    "management",
+    "manager",
+    "server",
+    "lifetimes",
+    "hierarchy",
+    "framework"
+  ],
   "scripts": {
     "prepare": "tsc && vite build",
     "test": "./bin/run-tests",
@@ -74,14 +83,14 @@
   },
   "devDependencies": {
     "@types/jest": "27.5.1",
-    "@typescript-eslint/eslint-plugin": "5.25.0",
-    "@typescript-eslint/parser": "5.25.0",
+    "@typescript-eslint/eslint-plugin": "5.26.0",
+    "@typescript-eslint/parser": "5.26.0",
     "eslint": "8.16.0",
     "husky": "8.0.1",
     "jest": "28.1.0",
     "lint-staged": "12.4.1",
     "prettier": "2.6.2",
-    "ts-jest": "28.0.2",
+    "ts-jest": "28.0.3",
     "typescript": "4.6.4",
     "vite": "2.9.9",
     "vite-dts": "1.0.4"

package/src/__tests__/allocation.test.ts

@@ -4,16 +4,16 @@ import { mount, unmount } from '../allocation';
 describe('allocation', () => {
   describe('mount', () => {
     it('allocates the resource', async () => {
-      const params = { test: 'init-args' };
+      const config = { test: 'init-args' };
       const enter = jest.fn();
 
-      class Test extends Resource<{ test: boolean }, { test: string }> {
+      class Test extends Resource<{ test: boolean }, [{ test: string }]> {
         exports = () => ({ test: true });
         enter = enter;
       }
 
-      await expect(mount(Test, params)).resolves.toEqual({ test: true });
-      expect(enter).toHaveBeenCalledWith(params);
+      await expect(mount(Test, config)).resolves.toEqual({ test: true });
+      expect(enter).toHaveBeenCalledWith(config);
     });
   });
 
@@ -26,10 +26,10 @@ describe('allocation', () => {
         leave = leave;
       }
 
-      const api = await mount(Test, null);
+      const test = await mount(Test);
 
       expect(leave).not.toHaveBeenCalled();
-      await expect(unmount(api)).resolves.not.toThrow();
+      await expect(unmount(test)).resolves.not.toThrow();
       expect(leave).toHaveBeenCalled();
     });
 
@@ -38,10 +38,10 @@ describe('allocation', () => {
         exports = () => [];
       }
 
-      const api = await mount(Test, null);
-      await unmount(api);
+      const test = await mount(Test);
+      await unmount(test);
 
-      await expect(unmount(api)).resolves.not.toThrow();
+      await expect(unmount(test)).resolves.not.toThrow();
     });
 
     it('automatically unmounts all children', async () => {
@@ -54,11 +54,11 @@ describe('allocation', () => {
       class Parent extends Resource<string[]> {
         exports = () => [];
         async enter() {
-          await this.allocate(Child, null);
+          await this.allocate(Child);
         }
       }
 
-      const parent = await mount(Parent, null);
+      const parent = await mount(Parent);
       await unmount(parent);
 
       expect(leave).toHaveBeenCalled();
@@ -76,11 +76,11 @@ describe('allocation', () => {
       class Parent extends Resource<string[]> {
         exports = () => [];
         async enter() {
-          await this.allocate(Child, null);
+          await this.allocate(Child);
         }
       }
 
-      const parent = await mount(Parent, null);
+      const parent = await mount(Parent);
       await expect(unmount(parent)).rejects.toThrow(error);
     });
   });

package/src/__tests__/resource.test.ts

@@ -1,5 +1,6 @@
-import Resource, { type ExternalControls } from '../resource';
+import Resource from '../resource';
 import { mount } from '../allocation';
+import { type Controls } from '../types';
 
 describe('Resource', () => {
   class Test extends Resource<Record<string, never>> {
@@ -18,16 +19,16 @@ describe('Resource', () => {
       exports = () => ({ child: true });
     }
 
-    class Parent extends Resource<ExternalControls<Child>> {
+    class Parent extends Resource<Controls<Child>> {
       exports = () => this.child;
-      child!: ExternalControls<Child>;
+      child!: Controls<Child>;
 
       async enter() {
-        this.child = await this.allocate(Child, null);
+        this.child = await this.allocate(Child);
       }
     }
 
-    await expect(mount(Parent, null)).resolves.toEqual({ child: true });
+    await expect(mount(Parent)).resolves.toEqual({ child: true });
   });
 
   it('can deallocate child resources on demand', async () => {
@@ -40,20 +41,20 @@ describe('Resource', () => {
 
     class Parent extends Resource<{ parent: boolean }> {
       exports = () => ({ parent: true });
-      child!: ExternalControls<Child>;
+      child!: Controls<Child>;
 
       async enter() {
-        const child = await this.allocate(Child, null);
+        const child = await this.allocate(Child);
         await this.deallocate(child);
       }
     }
 
-    await expect(mount(Parent, null)).resolves.toEqual({ parent: true });
+    await expect(mount(Parent)).resolves.toEqual({ parent: true });
     expect(leave).toHaveBeenCalled();
   });
 
   it('fails to destroy resources owned by someone else', async () => {
-    const test = await mount(Test, null);
+    const test = await mount(Test);
 
     class Sneaky extends Resource<string[]> {
       exports = () => [];
@@ -62,6 +63,6 @@ describe('Resource', () => {
       }
     }
 
-    await expect(mount(Sneaky, null)).rejects.toThrow(/do not own/i);
+    await expect(mount(Sneaky)).rejects.toThrow(/do not own/i);
   });
 });

package/src/allocation.ts

@@ -3,15 +3,18 @@ import { resources, ownership } from './state';
 import wrap from './proxy';
 
 /** Provision a resource and return its external API. */
-export async function mount<Api extends object, InitArgs>(
-  Subtype: new () => Resource<Api, InitArgs>,
-  params: InitArgs,
-): Promise<Api> {
-  const resource = new Subtype();
-  await resource.enter(params);
-
-  const api = resource.exports();
-  const { proxy, revoke } = wrap(api);
+export async function mount<
+  Controls extends object,
+  Args extends Array<unknown>,
+>(
+  Entity: new () => Resource<Controls, Args>,
+  ...args: Args
+): Promise<Controls> {
+  const resource = new Entity();
+  await resource.enter(...args);
+
+  const controls = resource.exports();
+  const { proxy, revoke } = wrap(controls);
 
   resources.set(proxy, {
     resource,
@@ -27,12 +30,12 @@ export async function mount<Api extends object, InitArgs>(
  *
  * @todo Add type marker to catch cases where the wrong object is unmounted.
  */
-export async function unmount(api: object) {
-  const entry = resources.get(api);
+export async function unmount(controls: object) {
+  const entry = resources.get(controls);
 
   if (entry) {
     // Instantly delete to prevent race conditions.
-    resources.delete(api);
+    resources.delete(controls);
 
     // Free all references.
     entry.revoke();
@@ -41,7 +44,7 @@ export async function unmount(api: object) {
     ownership.delete(entry.resource);
 
     // Recursively close out the children first...
-    const recursiveUnmounts = children.map((api) => unmount(api));
+    const recursiveUnmounts = children.map((controls) => unmount(controls));
     const results = await Promise.allSettled(recursiveUnmounts);
 
     // Then close the parent.

package/src/index.ts

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

package/src/resource.ts

@@ -7,8 +7,8 @@ import { ownership } from './state';
  * first tears down the children.
  */
 export default abstract class Resource<
-  ExternalApi extends object,
-  InitArgs = void,
+  Controls extends object,
+  Args extends Array<unknown> = [],
 > {
   #resources = new WeakSet<object>();
   #children: Array<object> = [];
@@ -19,7 +19,7 @@ export default abstract class Resource<
 
   /** A hook that gets called when the resource is created. */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async enter(_params: InitArgs) {
+  async enter(..._args: Args) {
     return;
   }
 
@@ -29,35 +29,32 @@ export default abstract class Resource<
   }
 
   /** Provision an owned resource and make sure it doesn't outlive us. */
-  async allocate<Api extends object, Params>(
-    Child: new () => Resource<Api, Params>,
-    params: Params,
-  ): Promise<Api> {
-    const api = await mount(Child, params);
-    this.#resources.add(api);
-    this.#children.push(api);
-
-    return api;
+  async allocate<
+    ChildControls extends object,
+    ChildArgs extends Array<unknown> = [],
+  >(
+    Child: new () => Resource<ChildControls, ChildArgs>,
+    ...args: ChildArgs
+  ): Promise<ChildControls> {
+    const controls = await mount(Child, ...args);
+    this.#resources.add(controls);
+    this.#children.push(controls);
+
+    return controls;
   }
 
   /**
    * Tear down a resource. Happens automatically when resource owners are
    * deallocated.
    */
-  async deallocate(api: object) {
-    if (!this.#resources.has(api)) {
+  async deallocate(resource: object) {
+    if (!this.#resources.has(resource)) {
       throw new Error('You do not own this resource.');
     }
 
-    return unmount(api);
+    return unmount(resource);
   }
 
   /** Returns an external API to the parent resource. */
-  abstract exports(): ExternalApi;
+  abstract exports(): Controls;
 }
-
-/** The `exports` type for a resource. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ExternalControls<ArbitraryResource extends Resource<any, any>> =
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ArbitraryResource extends Resource<infer Api, any> ? Api : never;

package/src/state.ts

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

package/src/types.ts

@@ -0,0 +1,8 @@
+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;