{"id":15707059,"url":"https://github.com/psychollama/wardens","last_synced_at":"2025-08-23T17:43:42.079Z","repository":{"id":36980477,"uuid":"494688418","full_name":"PsychoLlama/wardens","owner":"PsychoLlama","description":"A tiny framework for managing resources","archived":false,"fork":false,"pushed_at":"2025-05-05T20:15:36.000Z","size":1496,"stargazers_count":5,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-05T21:27:42.785Z","etag":null,"topics":["framework","hierarchy","lifetimes","managment","resource"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PsychoLlama.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-05-21T05:21:51.000Z","updated_at":"2025-05-05T20:15:04.000Z","dependencies_parsed_at":"2023-02-13T04:01:25.631Z","dependency_job_id":"5ea824cb-857c-4db9-935b-7ece53af499f","html_url":"https://github.com/PsychoLlama/wardens","commit_stats":{"total_commits":227,"total_committers":3,"mean_commits":75.66666666666667,"dds":0.3480176211453745,"last_synced_commit":"2596aae03012cc346a543a05e8c94cba15fc356e"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsychoLlama%2Fwardens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsychoLlama%2Fwardens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsychoLlama%2Fwardens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsychoLlama%2Fwardens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PsychoLlama","download_url":"https://codeload.github.com/PsychoLlama/wardens/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252798539,"owners_count":21805876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","hierarchy","lifetimes","managment","resource"],"created_at":"2024-10-03T20:35:31.280Z","updated_at":"2025-05-07T01:43:54.080Z","avatar_url":"https://github.com/PsychoLlama.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eWardens\u003c/h1\u003e\n  \u003cp\u003eA tiny framework for managing resources.\u003c/p\u003e\n  \u003cimg alt=\"Build status\" src=\"https://img.shields.io/github/actions/workflow/status/PsychoLlama/wardens/test.yml?branch=main\" /\u003e\n  \u003cimg alt=\"TypeScript\" src=\"https://img.shields.io/npm/types/wardens\" /\u003e\n  \u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/wardens\" /\u003e\n\u003c/div\u003e\n\n## Overview\n\nThis library is designed for applications that dynamically provision and deallocate hierarchical resources over time.\n\nHere's an example: let's say you've got a thread pool, one per CPU. Each thread gets a `Resource`, a small wrapper that hooks into setup and teardown controls.\n\n```typescript\nasync function Worker() {\n  const thread = await spawn();\n\n  return {\n    // The value returned after initialization completes\n    value: thread,\n\n    // Called when the resource is destroyed\n    destroy: () =\u003e thread.close(),\n  };\n}\n```\n\nNow define a pool that creates and manages workers:\n\n```typescript\nasync function WorkerPool(\n  { create }: ResourceScope,\n  config: { poolSize: number },\n) {\n  const promises = Array(config.poolSize).fill(Worker).map(create);\n  const threads = await Promise.all(promises);\n\n  return {\n    // ... External API goes here ...\n    value: {\n      doSomeWork() {},\n      doSomethingElse() {},\n    },\n  };\n}\n```\n\nFinally, create the pool:\n\n```typescript\nconst pool = await create(WorkerPool, {\n  poolSize: cpus().length,\n});\n\n// Provisioned and ready to go!\npool.doSomeWork();\npool.doSomethingElse();\n```\n\nThe magic of this framework is that resources never outlive their owners. If you tear down the pool, it will deallocate everything beneath it first:\n\n```typescript\nawait destroy(pool);\n\n// [info] closing worker\n// [info] closing worker\n// [info] closing worker\n// [info] closing worker\n// [info] closing pool\n```\n\nNo more forgotten resources.\n\n## Summary\n\nThe framework can be used to manage small pieces of stateful logic in your application, or it can scale to manage your entire server. Use the paradigm as much or as little as you like.\n\nI built this for my own projects. Documentation is a bit sparse, but enough GitHub stars could change that. This is a bribe.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsychollama%2Fwardens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpsychollama%2Fwardens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsychollama%2Fwardens/lists"}