@pumped-fn/lite 1.11.4 → 2.1.0

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":["categories: Record<string, { title: string; content: string | (() => string) }>"],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { readFileSync } from \"node:fs\"\nimport { dirname, join } from \"node:path\"\nimport { fileURLToPath } from \"node:url\"\n\nconst pkgDir = join(dirname(fileURLToPath(import.meta.url)), \"..\")\nconst readme = readFileSync(join(pkgDir, \"README.md\"), \"utf-8\")\n\nfunction extractOverview(): string {\n  const idx = readme.indexOf(\"## How It Works\")\n  const raw = idx === -1 ? readme : readme.slice(0, idx)\n  return raw.replace(/^#[^\\n]*\\n+/, \"\").trim()\n}\n\nfunction extractDiagram(): string {\n  const match = readme.match(/```mermaid\\n([\\s\\S]*?)```/)\n  return match ? `Full system sequence (unified):\\n\\n\\`\\`\\`mermaid\\n${match[1]!.trim()}\\n\\`\\`\\`` : \"No diagram found in README.md\"\n}\n\nconst categories: Record<string, { title: string; content: string | (() => string) }> = {\n  overview: {\n    title: \"What is @pumped-fn/lite\",\n    content: extractOverview,\n  },\n\n  primitives: {\n    title: \"Primitives API\",\n    content: `atom({ factory, deps?, tags?, keepAlive? })\n  Creates a managed effect. Factory receives (ctx, resolvedDeps) and returns a value.\n  Cached per scope. Supports cleanup via ctx.onClose().\n\n  import { atom } from \"@pumped-fn/lite\"\n  const dbAtom = atom({ factory: () => createDbPool() })\n  const userAtom = atom({\n    deps: { db: dbAtom },\n    factory: (ctx, { db }) => db.query(\"SELECT ...\"),\n  })\n\nflow({ factory, parse?, deps?, tags? })\n  Operation template executed per call. parse validates input, factory runs logic.\n\n  import { flow, typed } from \"@pumped-fn/lite\"\n  const getUser = flow({\n    parse: typed<{ id: string }>(),\n    deps: { db: dbAtom },\n    factory: (ctx, { db }) => db.findUser(ctx.input.id),\n  })\n\ntag({ label, default?, parse? })\n  Ambient context value. Attach to atoms/flows/contexts. Retrieve via tag.get/find/collect.\n\n  import { tag } from \"@pumped-fn/lite\"\n  const tenantTag = tag<string>({ label: \"tenant\" })\n\npreset(target, value)\n  Override an atom's resolved value. Used for testing and multi-tenant isolation.\n\n  import { preset } from \"@pumped-fn/lite\"\n  const mockDb = preset(dbAtom, fakeDatabaseInstance)\n\nservice({ factory, deps? })\n  Convenience wrapper for atom whose value is an object of methods.\n  Each method receives (ctx, ...args) for tracing/auth integration.`,\n  },\n\n  scope: {\n    title: \"Scope Management\",\n    content: `createScope({ extensions?, presets?, tags?, gc? })\n  Creates a scope that manages atom resolution, caching, extensions, and GC.\n\n  import { createScope } from \"@pumped-fn/lite\"\n  const scope = createScope({\n    extensions: [loggingExt],\n    presets: [preset(dbAtom, mockDb)],\n    tags: [tenantTag(\"acme\")],\n    gc: { enabled: true, graceMs: 3000 },\n  })\n  await scope.ready\n\nscope.resolve(atom)        → Promise<value>     resolve and cache an atom\nscope.controller(atom)     → Controller          get reactive handle\nscope.select(atom, fn, opts?) → SelectHandle     derived slice with equality check\nscope.on(event, atom, fn)  → unsubscribe         listen to atom events\nscope.release(atom)        → void                release atom, run cleanups\nscope.createContext(opts?)  → ExecutionContext    create execution boundary\nscope.flush()              → Promise<void>       wait all pending operations\nscope.dispose()            → void                release everything, run all cleanups`,\n  },\n\n  context: {\n    title: \"ExecutionContext\",\n    content: `ctx = scope.createContext({ tags? })\n  Execution boundary. Tags merge with scope tags. Cleanup runs LIFO on close.\n\nctx.exec({ flow, input?, tags? })  → Promise<output>\n  Execute a flow within this context. Creates a child context with merged tags.\n  Child context closes automatically after execution.\n\nctx.exec({ fn, params?, tags? })   → Promise<result>\n  Execute an inline function: fn(childCtx, ...params).\n  Same child-context lifecycle as flow execution.\n\nctx.onClose(cleanup)   → void     register cleanup (runs LIFO on ctx.close)\nctx.close()            → void     run all registered cleanups in LIFO order\n\nctx.data\n  Key-value store scoped to the context:\n    Raw:   get(key) / set(key, val) / has(key) / delete(key) / clear() / seek(key)\n    Typed: getTag(tag) / setTag(tag, val) / hasTag(tag) / deleteTag(tag) / seekTag(tag) / getOrSetTag(tag, factory)\n\n  seek/seekTag walks up the context chain to find values in parent contexts.`,\n  },\n\n  reactivity: {\n    title: \"Reactivity (opt-in)\",\n    content: `controller(atom)  → Controller\n  Opt-in reactive handle for an atom.\n\n  ctrl.get()                  → current value (must be resolved first)\n  ctrl.resolve()              → Promise<value> (resolve if not yet)\n  ctrl.set(value)             → replace value, notify listeners\n  ctrl.update(fn)             → update value via function, notify listeners\n  ctrl.invalidate()           → re-run factory, notify listeners\n  ctrl.release()              → release atom, run cleanups\n  ctrl.on(event, listener)    → unsubscribe\n    events: 'resolving' | 'resolved' | '*'\n\nselect(atom, selector, { eq? })  → SelectHandle\n  Derived state slice. Only notifies when selected value changes per eq function.\n\n  handle.get()              → current selected value\n  handle.subscribe(fn)      → unsubscribe\n\nscope.on('resolved', atom, listener)  → unsubscribe\n  Listen to atom resolution events at scope level.\n\nController as dependency:\n  import { controller } from \"@pumped-fn/lite\"\n  const serverAtom = atom({\n    deps: { cfg: controller(configAtom, { resolve: true }) },\n    factory: (ctx, { cfg }) => {\n      cfg.on('resolved', () => ctx.invalidate())\n      return createServer(cfg.get())\n    },\n  })`,\n  },\n\n  tags: {\n    title: \"Tag System\",\n    content: `tag<T>({ label, default?, parse? })  → Tag<T>\n  Define an ambient context value type.\n\ntag(value)  → Tagged<T>\n  Create a tagged value to attach to atoms, flows, or contexts.\n\nAttaching tags:\n  atom({ tags: [tenantTag(\"acme\")] })\n  flow({ tags: [roleTag(\"admin\")] })\n  scope.createContext({ tags: [userTag(currentUser)] })\n  ctx.exec({ flow, tags: [localeTag(\"en\")] })\n\nReading tags:\n  tag.get(source)      → T           first match or throw\n  tag.find(source)     → T | undefined   first match or undefined\n  tag.collect(source)  → T[]         all matches\n\nContext data integration:\n  ctx.data.setTag(tag, value)\n  ctx.data.getTag(tag)        → T\n  ctx.data.seekTag(tag)       → T (walks parent chain)\n  ctx.data.hasTag(tag)        → boolean\n\nTag executor (dependency wiring):\n  tags.required(tag)   → resolves tag or throws\n  tags.optional(tag)   → resolves tag or undefined\n  tags.all(tag)        → resolves all values for tag\n\nIntrospection:\n  tag.atoms()          → Atom[] with this tag attached\n  getAllTags()          → Tag[] all registered tags`,\n  },\n\n  extensions: {\n    title: \"Extensions Pipeline\",\n    content: `Extensions wrap atom resolution and flow execution (middleware pattern).\n\ninterface Extension {\n  init?(scope): void | Promise<void>\n  dispose?(scope): void\n  wrapResolve?(next, event: ResolveEvent): Promise<value>\n  wrapExec?(next, flow, ctx): Promise<output>\n}\n\ncreateScope({ extensions: [ext1, ext2] })\n\nLifecycle:\n  1. scope creation  → ext.init(scope) called for each extension\n  2. await scope.ready  → all init() resolved\n  3. resolve(atom)  → ext.wrapResolve(next, { kind: \"atom\", target, scope })\n     resolve(resource) → ext.wrapResolve(next, { kind: \"resource\", target, ctx })\n     - call next() to proceed to actual resolution\n     - dispatch on event.kind for atom vs resource\n  4. ctx.exec(flow)  → ext.wrapExec(next, flow, ctx)\n     - call next() to proceed to actual execution\n  5. scope.dispose()  → ext.dispose(scope) called for each extension\n\nExample:\n  const timingExt: Extension = {\n    wrapResolve: async (next, event) => {\n      const start = Date.now()\n      const value = await next()\n      console.log(event.target, Date.now() - start, \"ms\")\n      return value\n    },\n  }`,\n  },\n\n  testing: {\n    title: \"Testing & Isolation\",\n    content: `Use presets to swap implementations without changing production code.\n\nimport { createScope, preset } from \"@pumped-fn/lite\"\n\nconst scope = createScope({\n  presets: [\n    preset(dbAtom, mockDatabase),\n    preset(cacheAtom, inMemoryCache),\n  ],\n  tags: [tenantTag(\"test-tenant\")],\n})\n\nconst db = await scope.resolve(dbAtom)  // → mockDatabase (not real db)\n\nMulti-tenant isolation:\n  Each scope is fully isolated. Create one scope per tenant/test.\n\n  const tenantScope = createScope({\n    tags: [tenantTag(tenantId)],\n    presets: tenantOverrides,\n  })\n\nCleanup:\n  scope.dispose() releases all atoms and runs all cleanup functions.\n  In tests: call scope.dispose() in afterEach.`,\n  },\n\n  patterns: {\n    title: \"Common Patterns\",\n    content: `Request lifecycle:\n  const scope = createScope()\n  const ctx = scope.createContext({ tags: [requestTag(req)] })\n  const result = await ctx.exec({ flow: handleRequest, input: req.body })\n  ctx.close()  // cleanup LIFO\n\nService pattern:\n  const userService = service({\n    deps: { db: dbAtom },\n    factory: (ctx, { db }) => ({\n      getUser: (ctx, id) => db.findUser(id),\n      updateUser: (ctx, id, data) => db.updateUser(id, data),\n    }),\n  })\n\nTyped flow input:\n  const getUser = flow({\n    parse: typed<{ id: string }>(),\n    factory: (ctx) => findUser(ctx.input.id),\n  })\n\nInline execution:\n  const result = await ctx.exec({\n    fn: (ctx, a, b) => a + b,\n    params: [1, 2],\n  })\n\nAtom with cleanup:\n  const serverAtom = atom({\n    factory: (ctx) => {\n      const server = createServer()\n      ctx.onClose(() => server.close())\n      return server\n    },\n  })\n\nAtom retention / GC:\n  createScope({ gc: { enabled: true, graceMs: 3000 } })\n  atom({ keepAlive: true })  // never GC'd`,\n  },\n\n  diagrams: {\n    title: \"Visual Diagrams (mermaid)\",\n    content: extractDiagram,\n  },\n\n  types: {\n    title: \"Type Utilities & Guards\",\n    content: `Type extractors (Lite.Utils namespace):\n  AtomValue<A>          extract resolved type from atom\n  FlowOutput<F>         extract output type from flow\n  FlowInput<F>          extract input type from flow\n  TagValue<T>           extract value type from tag\n  DepsOf<A | F>         extract deps record type\n  ControllerValue<C>    extract value from controller\n  Simplify<T>           flatten intersection types\n  AtomType<T, D>        construct atom type\n  FlowType<O, I, D>     construct flow type\n\nType guards:\n  isAtom(v)             → v is Atom\n  isFlow(v)             → v is Flow\n  isTag(v)              → v is Tag\n  isTagged(v)           → v is Tagged\n  isPreset(v)           → v is Preset\n  isControllerDep(v)    → v is ControllerDep\n  isTagExecutor(v)      → v is TagExecutor\n\nConvenience types:\n  AnyAtom               any atom regardless of value/deps\n  AnyFlow               any flow regardless of output/input/deps\n  AnyController         any controller regardless of value\n\nSymbols (advanced, for library authors):\n  atomSymbol, flowSymbol, tagSymbol, taggedSymbol,\n  presetSymbol, controllerSymbol, controllerDepSymbol,\n  tagExecutorSymbol, typedSymbol`,\n  },\n}\n\nconst args = process.argv.slice(2)\nconst category = args[0]\n\nif (!category || category === \"help\" || category === \"--help\") {\n  console.log(\"@pumped-fn/lite — Scoped Ambient State for TypeScript\\n\")\n  console.log(\"Usage: pumped-lite <category>\\n\")\n  console.log(\"Categories:\")\n  for (const [key, { title }] of Object.entries(categories)) {\n    console.log(`  ${key.padEnd(14)} ${title}`)\n  }\n  console.log(\"\\nExamples:\")\n  console.log(\"  npx @pumped-fn/lite primitives   # API reference\")\n  console.log(\"  npx @pumped-fn/lite diagrams     # mermaid diagrams\")\n  process.exit(0)\n}\n\nif (!(category in categories)) {\n  console.error(`Unknown category: \"${category}\"\\n`)\n  console.error(\"Available categories: \" + Object.keys(categories).join(\", \"))\n  process.exit(1)\n}\n\nconst entry = categories[category]!\nconst output = typeof entry.content === \"function\" ? entry.content() : entry.content\nconsole.log(`# ${entry.title}\\n`)\nconsole.log(output)\n"],"mappings":";;;;;;AAOA,MAAM,SAAS,aAAa,KADb,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,KAAK,EACzB,YAAY,EAAE,QAAQ;AAE/D,SAAS,kBAA0B;CACjC,MAAM,MAAM,OAAO,QAAQ,kBAAkB;AAE7C,SADY,QAAQ,KAAK,SAAS,OAAO,MAAM,GAAG,IAAI,EAC3C,QAAQ,eAAe,GAAG,CAAC,MAAM;;AAG9C,SAAS,iBAAyB;CAChC,MAAM,QAAQ,OAAO,MAAM,4BAA4B;AACvD,QAAO,QAAQ,qDAAqD,MAAM,GAAI,MAAM,CAAC,YAAY;;AAGnG,MAAMA,aAAkF;CACtF,UAAU;EACR,OAAO;EACP,SAAS;EACV;CAED,YAAY;EACV,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoCV;CAED,OAAO;EACL,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;EAoBV;CAED,SAAS;EACP,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;EAoBV;CAED,YAAY;EACV,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BV;CAED,MAAM;EACJ,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BV;CAED,YAAY;EACV,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BV;CAED,SAAS;EACP,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;EAyBV;CAED,UAAU;EACR,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuCV;CAED,UAAU;EACR,OAAO;EACP,SAAS;EACV;CAED,OAAO;EACL,OAAO;EACP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BV;CACF;AAGD,MAAM,WADO,QAAQ,KAAK,MAAM,EAAE,CACZ;AAEtB,IAAI,CAAC,YAAY,aAAa,UAAU,aAAa,UAAU;AAC7D,SAAQ,IAAI,0DAA0D;AACtE,SAAQ,IAAI,kCAAkC;AAC9C,SAAQ,IAAI,cAAc;AAC1B,MAAK,MAAM,CAAC,KAAK,EAAE,YAAY,OAAO,QAAQ,WAAW,CACvD,SAAQ,IAAI,KAAK,IAAI,OAAO,GAAG,CAAC,GAAG,QAAQ;AAE7C,SAAQ,IAAI,cAAc;AAC1B,SAAQ,IAAI,qDAAqD;AACjE,SAAQ,IAAI,wDAAwD;AACpE,SAAQ,KAAK,EAAE;;AAGjB,IAAI,EAAE,YAAY,aAAa;AAC7B,SAAQ,MAAM,sBAAsB,SAAS,KAAK;AAClD,SAAQ,MAAM,2BAA2B,OAAO,KAAK,WAAW,CAAC,KAAK,KAAK,CAAC;AAC5E,SAAQ,KAAK,EAAE;;AAGjB,MAAM,QAAQ,WAAW;AACzB,MAAM,SAAS,OAAO,MAAM,YAAY,aAAa,MAAM,SAAS,GAAG,MAAM;AAC7E,QAAQ,IAAI,KAAK,MAAM,MAAM,IAAI;AACjC,QAAQ,IAAI,OAAO"}

package/dist/index.cjs

@@ -9,6 +9,7 @@ const presetSymbol = Symbol.for("@pumped-fn/lite/preset");
 const controllerSymbol = Symbol.for("@pumped-fn/lite/controller");
 const tagExecutorSymbol = Symbol.for("@pumped-fn/lite/tag-executor");
 const typedSymbol = Symbol.for("@pumped-fn/lite/typed");
+const resourceSymbol = Symbol.for("@pumped-fn/lite/resource");
 
 //#endregion
 //#region src/errors.ts
@@ -262,20 +263,33 @@ function isAtom(value) {
 * The Controller provides full lifecycle control: get, resolve, release, invalidate, and subscribe.
 *
 * @param atom - The Atom to wrap
-* @param options - Optional configuration. Use { resolve: true } to auto-resolve before factory runs.
+* @param options - Optional configuration:
+*   - `resolve: true` — auto-resolves the dep before the parent factory runs; `config.get()` is safe.
+*   - `watch: true` — atom deps only; requires `resolve: true`; automatically re-runs the parent factory
+*     when the dep resolves to a new value (value-equality gated via `Object.is` by default). Replaces
+*     manual `ctx.cleanup(ctx.scope.on('resolved', dep, () => ctx.invalidate()))` wiring. Watch
+*     listeners are auto-cleaned on re-resolve, release, and dispose.
+*   - `eq` — custom equality function `(a: T, b: T) => boolean`; only used with `watch: true`.
 * @returns A ControllerDep that resolves to a Controller for the Atom
 *
 * @example
 * ```typescript
-* const configAtom = atom({ factory: () => fetchConfig() })
+* // resolve only
 * const serverAtom = atom({
 *   deps: { config: controller(configAtom, { resolve: true }) },
-*   factory: (ctx, { config }) => {
-*     // config.get() is safe - already resolved
-*     const unsub = config.on('resolved', () => ctx.invalidate())
-*     ctx.cleanup(unsub)
-*     return createServer(config.get().port)
-*   }
+*   factory: (_, { config }) => createServer(config.get().port),
+* })
+*
+* // watch: re-runs parent when dep value changes
+* const profileAtom = atom({
+*   deps: { token: controller(tokenAtom, { resolve: true, watch: true }) },
+*   factory: (_, { token }) => ({ id: `user-${token.get().jwt}` }),
+* })
+*
+* // watch with custom equality
+* const derivedAtom = atom({
+*   deps: { src: controller(srcAtom, { resolve: true, watch: true, eq: (a, b) => a.id === b.id }) },
+*   factory: (_, { src }) => src.get().name,
 * })
 * ```
 */
@@ -283,7 +297,9 @@ function controller(atom$1, options) {
 	return {
 		[controllerDepSymbol]: true,
 		atom: atom$1,
-		resolve: options?.resolve
+		resolve: options?.resolve,
+		watch: options?.watch,
+		eq: options?.eq
 	};
 }
 /**
@@ -379,6 +395,33 @@ function isPreset(value) {
 	return typeof value === "object" && value !== null && value[presetSymbol] === true;
 }
 
+//#endregion
+//#region src/resource.ts
+function resource(config) {
+	return Object.freeze({
+		[resourceSymbol]: true,
+		name: config.name,
+		deps: config.deps,
+		factory: config.factory
+	});
+}
+/**
+* Type guard to check if a value is a Resource.
+*
+* @param value - The value to check
+* @returns True if the value is a Resource, false otherwise
+*
+* @example
+* ```typescript
+* if (isResource(value)) {
+*   // value is Lite.Resource<unknown>
+* }
+* ```
+*/
+function isResource(value) {
+	return typeof value === "object" && value !== null && value[resourceSymbol] === true;
+}
+
 //#endregion
 //#region src/service.ts
 function service(config) {
@@ -392,6 +435,18 @@ function service(config) {
 
 //#endregion
 //#region src/scope.ts
+const resourceKeys = /* @__PURE__ */ new WeakMap();
+let resourceKeyCounter = 0;
+function getResourceKey(resource$1) {
+	let key = resourceKeys.get(resource$1);
+	if (!key) {
+		key = Symbol(`resource:${resource$1.name ?? resourceKeyCounter++}`);
+		resourceKeys.set(resource$1, key);
+	}
+	return key;
+}
+const inflightResources = /* @__PURE__ */ new WeakMap();
+const resolvingResources = /* @__PURE__ */ new Set();
 var ContextDataImpl = class {
 	map = /* @__PURE__ */ new Map();
 	constructor(parentData) {
@@ -731,6 +786,8 @@ var ScopeImpl = class {
 	async doResolve(atom$1) {
 		const entry = this.getOrCreateEntry(atom$1);
 		if (!(entry.state === "resolving")) {
+			for (let i = entry.cleanups.length - 1; i >= 0; i--) await entry.cleanups[i]?.();
+			entry.cleanups = [];
 			entry.state = "resolving";
 			this.emitStateChange("resolving", atom$1);
 			this.notifyListeners(atom$1, "resolving");
@@ -753,7 +810,12 @@ var ScopeImpl = class {
 			else return factory(ctx);
 		};
 		try {
-			const value = await this.applyResolveExtensions(atom$1, doResolve);
+			const event = {
+				kind: "atom",
+				target: atom$1,
+				scope: this
+			};
+			const value = await this.applyResolveExtensions(event, doResolve);
 			entry.state = "resolved";
 			entry.value = value;
 			entry.hasValue = true;
@@ -784,13 +846,13 @@ var ScopeImpl = class {
 			throw entry.error;
 		}
 	}
-	async applyResolveExtensions(atom$1, doResolve) {
+	async applyResolveExtensions(event, doResolve) {
 		let next = doResolve;
 		for (let i = this.extensions.length - 1; i >= 0; i--) {
 			const ext = this.extensions[i];
 			if (ext?.wrapResolve) {
 				const currentNext = next;
-				next = ext.wrapResolve.bind(ext, currentNext, atom$1, this);
+				next = ext.wrapResolve.bind(ext, currentNext, event);
 			}
 		}
 		return next();
@@ -805,13 +867,31 @@ var ScopeImpl = class {
 				if (depEntry) depEntry.dependents.add(dependentAtom);
 			}
 		} else if (isControllerDep(dep)) {
-			const ctrl = new ControllerImpl(dep.atom, this);
+			if (dep.watch) {
+				if (!dependentAtom) throw new Error("controller({ watch: true }) is only supported in atom dependencies");
+				if (!dep.resolve) throw new Error("controller({ watch: true }) requires resolve: true");
+			}
+			const ctrl = this.controller(dep.atom);
 			if (dep.resolve) await ctrl.resolve();
 			result[key] = ctrl;
 			if (dependentAtom) {
 				const depEntry = this.getEntry(dep.atom);
 				if (depEntry) depEntry.dependents.add(dependentAtom);
 			}
+			if (dep.watch) {
+				const eq = dep.eq ?? Object.is;
+				let prev = ctrl.get();
+				const unsub = this.on("resolved", dep.atom, () => {
+					const next = ctrl.get();
+					if (!eq(prev, next)) {
+						prev = next;
+						this.scheduleInvalidation(dependentAtom);
+					}
+				});
+				const depEntry = this.getEntry(dependentAtom);
+				if (depEntry) depEntry.cleanups.push(unsub);
+				else unsub();
+			}
 		} else if (tagExecutorSymbol in dep) {
 			const tagExecutor = dep;
 			switch (tagExecutor.mode) {
@@ -829,6 +909,59 @@ var ScopeImpl = class {
 					result[key] = ctx ? this.collectFromHierarchy(ctx, tagExecutor.tag) : tagExecutor.tag.collect(this.tags);
 					break;
 			}
+		} else if (isResource(dep)) {
+			if (!ctx) throw new Error("Resource deps require an ExecutionContext");
+			const resource$1 = dep;
+			const resourceKey = getResourceKey(resource$1);
+			const storeCtx = ctx.parent ?? ctx;
+			if (storeCtx.data.has(resourceKey)) {
+				result[key] = storeCtx.data.get(resourceKey);
+				continue;
+			}
+			const existingSeek = ctx.data.seek(resourceKey);
+			if (existingSeek !== void 0 || ctx.data.has(resourceKey)) {
+				result[key] = existingSeek;
+				continue;
+			}
+			if (resolvingResources.has(resourceKey)) throw new Error(`Circular resource dependency detected: ${resource$1.name ?? "anonymous"}`);
+			let flights = inflightResources.get(storeCtx.data);
+			if (!flights) {
+				flights = /* @__PURE__ */ new Map();
+				inflightResources.set(storeCtx.data, flights);
+			}
+			const inflight = flights.get(resourceKey);
+			if (inflight) {
+				result[key] = await inflight;
+				continue;
+			}
+			const resolve = async () => {
+				resolvingResources.add(resourceKey);
+				try {
+					const resourceDeps = await this.resolveDeps(resource$1.deps, ctx);
+					const event = {
+						kind: "resource",
+						target: resource$1,
+						ctx: storeCtx
+					};
+					const doResolve = async () => {
+						const factory = resource$1.factory;
+						if (resource$1.deps && Object.keys(resource$1.deps).length > 0) return factory(storeCtx, resourceDeps);
+						return factory(storeCtx);
+					};
+					const value = await this.applyResolveExtensions(event, doResolve);
+					storeCtx.data.set(resourceKey, value);
+					return value;
+				} finally {
+					resolvingResources.delete(resourceKey);
+				}
+			};
+			const promise = resolve();
+			flights.set(resourceKey, promise);
+			try {
+				result[key] = await promise;
+			} finally {
+				flights.delete(resourceKey);
+			}
 		}
 		return result;
 	}
@@ -1006,10 +1139,15 @@ var ExecutionContextImpl = class ExecutionContextImpl {
 			for (const tagged of execTags ?? []) childCtx.data.set(tagged.key, tagged.value);
 			for (const tagged of flow$1.tags ?? []) if (!childCtx.data.has(tagged.key)) childCtx.data.set(tagged.key, tagged.value);
 			try {
-				if (presetValue !== void 0 && typeof presetValue === "function") return await childCtx.execPresetFn(flow$1, presetValue);
-				return await childCtx.execFlowInternal(flow$1);
-			} finally {
-				await childCtx.close();
+				const result = presetValue !== void 0 && typeof presetValue === "function" ? await childCtx.execPresetFn(flow$1, presetValue) : await childCtx.execFlowInternal(flow$1);
+				await childCtx.close({ ok: true });
+				return result;
+			} catch (error) {
+				await childCtx.close({
+					ok: false,
+					error
+				});
+				throw error;
 			}
 		} else {
 			const childCtx = new ExecutionContextImpl(this.scope, {
@@ -1019,9 +1157,15 @@ var ExecutionContextImpl = class ExecutionContextImpl {
 				input: options.params
 			});
 			try {
-				return await childCtx.execFnInternal(options);
-			} finally {
-				await childCtx.close();
+				const result = await childCtx.execFnInternal(options);
+				await childCtx.close({ ok: true });
+				return result;
+			} catch (error) {
+				await childCtx.close({
+					ok: false,
+					error
+				});
+				throw error;
 			}
 		}
 	}
@@ -1057,12 +1201,12 @@ var ExecutionContextImpl = class ExecutionContextImpl {
 	onClose(fn) {
 		this.cleanups.push(fn);
 	}
-	async close() {
+	async close(result = { ok: true }) {
 		if (this.closed) return;
 		this.closed = true;
 		for (let i = this.cleanups.length - 1; i >= 0; i--) {
 			const cleanup = this.cleanups[i];
-			if (cleanup) await cleanup();
+			if (cleanup) await cleanup(result);
 		}
 	}
 };
@@ -1115,11 +1259,14 @@ exports.isAtom = isAtom;
 exports.isControllerDep = isControllerDep;
 exports.isFlow = isFlow;
 exports.isPreset = isPreset;
+exports.isResource = isResource;
 exports.isTag = isTag;
 exports.isTagExecutor = isTagExecutor;
 exports.isTagged = isTagged;
 exports.preset = preset;
 exports.presetSymbol = presetSymbol;
+exports.resource = resource;
+exports.resourceSymbol = resourceSymbol;
 exports.service = service;
 exports.tag = tag;
 exports.tagExecutorSymbol = tagExecutorSymbol;

package/dist/index.d.cts

@@ -8,6 +8,7 @@ declare const presetSymbol: unique symbol;
 declare const controllerSymbol: unique symbol;
 declare const tagExecutorSymbol: unique symbol;
 declare const typedSymbol: unique symbol;
+declare const resourceSymbol: unique symbol;
 //#endregion
 //#region src/types.d.ts
 type MaybePromise<T> = T | Promise<T>;
@@ -58,6 +59,12 @@ declare namespace Lite {
     readonly deps?: Record<string, Dependency>;
     readonly tags?: Tagged<any>[];
   }
+  interface Resource<T, D extends Record<string, Dependency> = Record<string, Dependency>> {
+    readonly [resourceSymbol]: true;
+    readonly name?: string;
+    readonly deps?: D;
+    readonly factory: ResourceFactory<T, D>;
+  }
   /**
    * Unified context data storage with both raw Map operations and Tag-based DX.
    */
@@ -112,6 +119,12 @@ declare namespace Lite {
     readonly scope: Scope;
     readonly data: ContextData;
   }
+  type CloseResult = {
+    ok: true;
+  } | {
+    ok: false;
+    error: unknown;
+  };
   interface ExecutionContext {
     readonly input: unknown;
     readonly name: string | undefined;
@@ -120,8 +133,8 @@ declare namespace Lite {
     readonly data: ContextData;
     exec<Output, Input>(options: ExecFlowOptions<Output, Input>): Promise<Output>;
     exec<Output, Args extends unknown[]>(options: ExecFnOptions<Output, Args>): Promise<Output>;
-    onClose(fn: () => MaybePromise<void>): void;
-    close(): Promise<void>;
+    onClose(fn: (result: CloseResult) => MaybePromise<void>): void;
+    close(result?: CloseResult): Promise<void>;
   }
   type ExecFlowOptions<Output, Input> = {
     flow: Flow<Output, Input>;
@@ -217,10 +230,17 @@ declare namespace Lite {
     readonly [controllerDepSymbol]: true;
     readonly atom: Atom<T>;
     readonly resolve?: boolean;
+    readonly watch?: boolean;
+    readonly eq?: (a: any, b: any) => boolean;
   }
   interface ControllerOptions {
     resolve?: boolean;
   }
+  interface ControllerDepOptions<T> {
+    resolve?: boolean;
+    watch?: boolean;
+    eq?: (a: T, b: T) => boolean;
+  }
   interface Typed<T> {
     readonly [typedSymbol]: true;
   }
@@ -233,15 +253,38 @@ declare namespace Lite {
     readonly target: PresetTarget<T, I>;
     readonly value: PresetValue<T, I>;
   }
+  /**
+   * Discriminated context for `wrapResolve`.
+   *
+   * - `"atom"` — scope-level singleton. Cached after first resolve.
+   * - `"resource"` — execution-level. Fresh factory per first encounter,
+   *   seek-up on nested execs within the same chain.
+   */
+  type ResolveEvent = {
+    readonly kind: "atom";
+    readonly target: Atom<unknown>;
+    readonly scope: Scope;
+  } | {
+    readonly kind: "resource";
+    readonly target: Resource<unknown>;
+    readonly ctx: ExecutionContext;
+  };
   interface Extension {
     readonly name: string;
     init?(scope: Scope): MaybePromise<void>;
-    wrapResolve?(next: () => Promise<unknown>, atom: Atom<unknown>, scope: Scope): Promise<unknown>;
+    /**
+     * Wraps dependency resolution. Dispatch by `event.kind`:
+     *
+     * - `"atom"` — `event.scope`, `event.target: Atom`. Cached in scope.
+     * - `"resource"` — `event.ctx`, `event.target: Resource`. Seek-up in
+     *   execution hierarchy, factory(ctx, deps) on miss.
+     */
+    wrapResolve?(next: () => Promise<unknown>, event: ResolveEvent): Promise<unknown>;
     wrapExec?(next: () => Promise<unknown>, target: ExecTarget, ctx: ExecutionContext): Promise<unknown>;
     dispose?(scope: Scope): MaybePromise<void>;
   }
-  type Dependency = Atom<unknown> | ControllerDep<unknown> | TagExecutor<any>;
-  type InferDep<D> = D extends Atom<infer T> ? T : D extends ControllerDep<infer T> ? Controller<T> : D extends TagExecutor<infer TOutput, infer _TTag> ? TOutput : never;
+  type Dependency = Atom<unknown> | ControllerDep<unknown> | TagExecutor<any> | Resource<unknown>;
+  type InferDep<D> = D extends Atom<infer T> ? T : D extends ControllerDep<infer T> ? Controller<T> : D extends TagExecutor<infer TOutput, infer _TTag> ? TOutput : D extends Resource<infer T> ? T : never;
   type InferDeps<D> = { [K in keyof D]: InferDep<D[K]> };
   type AtomFactory<T, D extends Record<string, Dependency>> = keyof D extends never ? (ctx: ResolveContext) => MaybePromise<T> : (ctx: ResolveContext, deps: InferDeps<D>) => MaybePromise<T>;
   type FlowFactory<Output, Input, D extends Record<string, Dependency>> = keyof D extends never ? (ctx: ExecutionContext & {
@@ -249,6 +292,7 @@ declare namespace Lite {
   }) => MaybePromise<Output> : (ctx: ExecutionContext & {
     readonly input: Input;
   }, deps: InferDeps<D>) => MaybePromise<Output>;
+  type ResourceFactory<T, D extends Record<string, Dependency>> = keyof D extends never ? (ctx: ExecutionContext) => MaybePromise<T> : (ctx: ExecutionContext, deps: InferDeps<D>) => MaybePromise<T>;
   type ServiceMethod = (ctx: ExecutionContext, ...args: any[]) => unknown;
   type ServiceMethods = Record<string, ServiceMethod>;
   /**
@@ -265,6 +309,10 @@ declare namespace Lite {
    * Any controller regardless of value type.
    */
   type AnyController = Controller<any>;
+  /**
+   * Any resource regardless of value type.
+   */
+  type AnyResource = Resource<any>;
   /**
    * Target type for wrapExec extension hook.
    * Either a Flow or an inline function.
@@ -531,24 +579,37 @@ declare function isAtom(value: unknown): value is Lite.Atom<unknown>;
  * The Controller provides full lifecycle control: get, resolve, release, invalidate, and subscribe.
  *
  * @param atom - The Atom to wrap
- * @param options - Optional configuration. Use { resolve: true } to auto-resolve before factory runs.
+ * @param options - Optional configuration:
+ *   - `resolve: true` — auto-resolves the dep before the parent factory runs; `config.get()` is safe.
+ *   - `watch: true` — atom deps only; requires `resolve: true`; automatically re-runs the parent factory
+ *     when the dep resolves to a new value (value-equality gated via `Object.is` by default). Replaces
+ *     manual `ctx.cleanup(ctx.scope.on('resolved', dep, () => ctx.invalidate()))` wiring. Watch
+ *     listeners are auto-cleaned on re-resolve, release, and dispose.
+ *   - `eq` — custom equality function `(a: T, b: T) => boolean`; only used with `watch: true`.
  * @returns A ControllerDep that resolves to a Controller for the Atom
  *
  * @example
  * ```typescript
- * const configAtom = atom({ factory: () => fetchConfig() })
+ * // resolve only
  * const serverAtom = atom({
  *   deps: { config: controller(configAtom, { resolve: true }) },
- *   factory: (ctx, { config }) => {
- *     // config.get() is safe - already resolved
- *     const unsub = config.on('resolved', () => ctx.invalidate())
- *     ctx.cleanup(unsub)
- *     return createServer(config.get().port)
- *   }
+ *   factory: (_, { config }) => createServer(config.get().port),
+ * })
+ *
+ * // watch: re-runs parent when dep value changes
+ * const profileAtom = atom({
+ *   deps: { token: controller(tokenAtom, { resolve: true, watch: true }) },
+ *   factory: (_, { token }) => ({ id: `user-${token.get().jwt}` }),
+ * })
+ *
+ * // watch with custom equality
+ * const derivedAtom = atom({
+ *   deps: { src: controller(srcAtom, { resolve: true, watch: true, eq: (a, b) => a.id === b.id }) },
+ *   factory: (_, { src }) => src.get().name,
  * })
  * ```
  */
-declare function controller<T>(atom: Lite.Atom<T>, options?: Lite.ControllerOptions): Lite.ControllerDep<T>;
+declare function controller<T>(atom: Lite.Atom<T>, options?: Lite.ControllerDepOptions<T>): Lite.ControllerDep<T>;
 /**
  * Type guard to check if a value is a ControllerDep wrapper.
  *
@@ -621,7 +682,7 @@ declare function flow<TOutput, TInput>(config: {
   }) => MaybePromise<TOutput>;
   tags?: Lite.Tagged<any>[];
 }): Lite.Flow<TOutput, TInput>;
-declare function flow<TOutput, const D extends Record<string, Lite.Atom<unknown> | Lite.ControllerDep<unknown> | {
+declare function flow<TOutput, const D extends Record<string, Lite.Atom<unknown> | Lite.ControllerDep<unknown> | Lite.Resource<unknown, Record<string, Lite.Dependency>> | {
   mode: string;
 }>>(config: {
   name?: string;
@@ -630,7 +691,7 @@ declare function flow<TOutput, const D extends Record<string, Lite.Atom<unknown>
   factory: (ctx: Lite.ExecutionContext, deps: Lite.InferDeps<D>) => MaybePromise<TOutput>;
   tags?: Lite.Tagged<any>[];
 }): Lite.Flow<TOutput, void>;
-declare function flow<TOutput, TInput, const D extends Record<string, Lite.Atom<unknown> | Lite.ControllerDep<unknown> | {
+declare function flow<TOutput, TInput, const D extends Record<string, Lite.Atom<unknown> | Lite.ControllerDep<unknown> | Lite.Resource<unknown, Record<string, Lite.Dependency>> | {
   mode: string;
 }>>(config: {
   name?: string;
@@ -641,7 +702,7 @@ declare function flow<TOutput, TInput, const D extends Record<string, Lite.Atom<
   }, deps: Lite.InferDeps<D>) => MaybePromise<TOutput>;
   tags?: Lite.Tagged<any>[];
 }): Lite.Flow<TOutput, TInput>;
-declare function flow<TOutput, TInput, const D extends Record<string, Lite.Atom<unknown> | Lite.ControllerDep<unknown> | {
+declare function flow<TOutput, TInput, const D extends Record<string, Lite.Atom<unknown> | Lite.ControllerDep<unknown> | Lite.Resource<unknown, Record<string, Lite.Dependency>> | {
   mode: string;
 }>>(config: {
   name?: string;
@@ -721,6 +782,53 @@ declare function preset<TOutput, TInput>(target: Lite.Flow<TOutput, TInput>, val
  */
 declare function isPreset(value: unknown): value is Lite.Preset<unknown>;
 //#endregion
+//#region src/resource.d.ts
+/**
+ * Creates an execution-scoped dependency that is resolved per execution chain.
+ * Fresh instance on first encounter, seek-up on nested execs within the same chain.
+ *
+ * @param config - Configuration object containing factory function and optional dependencies
+ * @returns A Resource instance that can be declared as a dependency in flows and other resources
+ *
+ * @example
+ * ```typescript
+ * const requestLogger = resource({
+ *   deps: { logService: logServiceAtom },
+ *   factory: (ctx, { logService }) => {
+ *     const logger = logService.child({ requestId: ctx.data.get("requestId") })
+ *     ctx.onClose(() => logger.flush())
+ *     return logger
+ *   }
+ * })
+ * ```
+ */
+declare function resource<T>(config: {
+  name?: string;
+  deps?: undefined;
+  factory: (ctx: Lite.ExecutionContext) => MaybePromise<T>;
+}): Lite.Resource<T>;
+declare function resource<T, const D extends Record<string, Lite.Atom<unknown> | Lite.ControllerDep<unknown> | Lite.Resource<unknown, Record<string, Lite.Dependency>> | {
+  mode: string;
+}>>(config: {
+  name?: string;
+  deps: D;
+  factory: (ctx: Lite.ExecutionContext, deps: Lite.InferDeps<D>) => MaybePromise<T>;
+}): Lite.Resource<T>;
+/**
+ * Type guard to check if a value is a Resource.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Resource, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isResource(value)) {
+ *   // value is Lite.Resource<unknown>
+ * }
+ * ```
+ */
+declare function isResource(value: unknown): value is Lite.Resource<unknown>;
+//#endregion
 //#region src/service.d.ts
 /** Creates an atom with methods constrained to (ctx: ExecutionContext, ...args) => result. */
 declare function service<T extends Lite.ServiceMethods>(config: {
@@ -774,5 +882,5 @@ declare class ParseError extends Error {
 //#region src/index.d.ts
 declare const VERSION = "0.0.1";
 //#endregion
-export { type AtomState, type Lite, ParseError, VERSION, atom, atomSymbol, controller, controllerDepSymbol, controllerSymbol, createScope, flow, flowSymbol, getAllTags, isAtom, isControllerDep, isFlow, isPreset, isTag, isTagExecutor, isTagged, preset, presetSymbol, service, tag, tagExecutorSymbol, tagSymbol, taggedSymbol, tags, typed, typedSymbol };
+export { type AtomState, type Lite, ParseError, VERSION, atom, atomSymbol, controller, controllerDepSymbol, controllerSymbol, createScope, flow, flowSymbol, getAllTags, isAtom, isControllerDep, isFlow, isPreset, isResource, isTag, isTagExecutor, isTagged, preset, presetSymbol, resource, resourceSymbol, service, tag, tagExecutorSymbol, tagSymbol, taggedSymbol, tags, typed, typedSymbol };
 //# sourceMappingURL=index.d.cts.map