@pumped-fn/lite 0.1.0

package/dist/index.cjs

@@ -0,0 +1,647 @@
+
+//#region src/symbols.ts
+const atomSymbol = Symbol.for("@pumped-fn/lite/atom");
+const flowSymbol = Symbol.for("@pumped-fn/lite/flow");
+const tagSymbol = Symbol.for("@pumped-fn/lite/tag");
+const taggedSymbol = Symbol.for("@pumped-fn/lite/tagged");
+const controllerDepSymbol = Symbol.for("@pumped-fn/lite/controller-dep");
+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");
+
+//#endregion
+//#region src/tag.ts
+function tag(options) {
+	const key = Symbol.for(`@pumped-fn/lite/tag/${options.label}`);
+	const hasDefault = "default" in options;
+	const defaultValue = hasDefault ? options.default : void 0;
+	function createTagged(value) {
+		return {
+			[taggedSymbol]: true,
+			key,
+			value
+		};
+	}
+	function get(source) {
+		const tags$1 = Array.isArray(source) ? source : source.tags ?? [];
+		for (let i = 0; i < tags$1.length; i++) if (tags$1[i].key === key) return tags$1[i].value;
+		if (hasDefault) return defaultValue;
+		throw new Error(`Tag "${options.label}" not found and has no default`);
+	}
+	function find(source) {
+		const tags$1 = Array.isArray(source) ? source : source.tags ?? [];
+		for (let i = 0; i < tags$1.length; i++) if (tags$1[i].key === key) return tags$1[i].value;
+		if (hasDefault) return defaultValue;
+	}
+	function collect(source) {
+		const tags$1 = Array.isArray(source) ? source : source.tags ?? [];
+		const result = [];
+		for (let i = 0; i < tags$1.length; i++) if (tags$1[i].key === key) result.push(tags$1[i].value);
+		return result;
+	}
+	return Object.assign(createTagged, {
+		[tagSymbol]: true,
+		key,
+		label: options.label,
+		hasDefault,
+		defaultValue,
+		get,
+		find,
+		collect
+	});
+}
+/**
+* Type guard to check if a value is a Tag.
+*
+* @param value - The value to check
+* @returns True if the value is a Tag, false otherwise
+*
+* @example
+* ```typescript
+* if (isTag(value)) {
+*   const tagged = value("myValue")
+* }
+* ```
+*/
+function isTag(value) {
+	return typeof value === "function" && value[tagSymbol] === true;
+}
+/**
+* Type guard to check if a value is a Tagged value.
+*
+* @param value - The value to check
+* @returns True if the value is a Tagged value, false otherwise
+*
+* @example
+* ```typescript
+* if (isTagged(value)) {
+*   console.log(value.key, value.value)
+* }
+* ```
+*/
+function isTagged(value) {
+	return typeof value === "object" && value !== null && value[taggedSymbol] === true;
+}
+/**
+* Tag execution helpers for declaring how tags should be resolved from dependency sources.
+*/
+const tags = {
+	required(tag$1) {
+		return {
+			[tagExecutorSymbol]: true,
+			tag: tag$1,
+			mode: "required"
+		};
+	},
+	optional(tag$1) {
+		return {
+			[tagExecutorSymbol]: true,
+			tag: tag$1,
+			mode: "optional"
+		};
+	},
+	all(tag$1) {
+		return {
+			[tagExecutorSymbol]: true,
+			tag: tag$1,
+			mode: "all"
+		};
+	}
+};
+/**
+* Type guard to check if a value is a TagExecutor.
+*
+* @param value - The value to check
+* @returns True if the value is a TagExecutor, false otherwise
+*
+* @example
+* ```typescript
+* if (isTagExecutor(value)) {
+*   console.log(value.mode, value.tag)
+* }
+* ```
+*/
+function isTagExecutor(value) {
+	return typeof value === "object" && value !== null && tagExecutorSymbol in value;
+}
+
+//#endregion
+//#region src/atom.ts
+function atom(config) {
+	return {
+		[atomSymbol]: true,
+		factory: config.factory,
+		deps: config.deps,
+		tags: config.tags
+	};
+}
+/**
+* Type guard to check if a value is an Atom.
+*
+* @param value - The value to check
+* @returns True if the value is an Atom, false otherwise
+*
+* @example
+* ```typescript
+* if (isAtom(value)) {
+*   await scope.resolve(value)
+* }
+* ```
+*/
+function isAtom(value) {
+	return typeof value === "object" && value !== null && value[atomSymbol] === true;
+}
+/**
+* Wraps an Atom to receive a Controller instead of the resolved value.
+* The Controller provides full lifecycle control: get, resolve, release, invalidate, and subscribe.
+*
+* @param atom - The Atom to wrap
+* @returns A ControllerDep that resolves to a Controller for the Atom
+*
+* @example
+* ```typescript
+* const configAtom = atom({ factory: () => fetchConfig() })
+* const serverAtom = atom({
+*   deps: { config: controller(configAtom) },
+*   factory: (ctx, { config }) => {
+*     const unsub = config.on(() => ctx.invalidate())
+*     ctx.cleanup(unsub)
+*     return createServer(config.get().port)
+*   }
+* })
+* ```
+*/
+function controller(atom$1) {
+	return {
+		[controllerDepSymbol]: true,
+		atom: atom$1
+	};
+}
+/**
+* Type guard to check if a value is a ControllerDep wrapper.
+*
+* @param value - The value to check
+* @returns True if the value is a ControllerDep wrapper, false otherwise
+*
+* @example
+* ```typescript
+* if (isControllerDep(dep)) {
+*   const ctrl = scope.controller(dep.atom)
+* }
+* ```
+*/
+function isControllerDep(value) {
+	return typeof value === "object" && value !== null && value[controllerDepSymbol] === true;
+}
+
+//#endregion
+//#region src/flow.ts
+function flow(config) {
+	return {
+		[flowSymbol]: true,
+		factory: config.factory,
+		deps: config.deps,
+		tags: config.tags
+	};
+}
+/**
+* Type guard to check if a value is a Flow.
+*
+* @param value - The value to check
+* @returns True if the value is a Flow, false otherwise
+*
+* @example
+* ```typescript
+* if (isFlow(value)) {
+*   await ctx.exec({ flow: value, input: data })
+* }
+* ```
+*/
+function isFlow(value) {
+	return typeof value === "object" && value !== null && value[flowSymbol] === true;
+}
+
+//#endregion
+//#region src/preset.ts
+/**
+* Creates a preset value for an Atom, overriding its factory within a scope.
+*
+* @param atom - The Atom to preset
+* @param value - The preset value (can be a direct value or another Atom)
+* @returns A Preset instance to be used in scope configuration
+*
+* @example
+* ```typescript
+* const scope = await createScope({
+*   presets: [preset(dbAtom, mockDatabase)]
+* })
+* ```
+*/
+function preset(atom$1, value) {
+	return {
+		[presetSymbol]: true,
+		atom: atom$1,
+		value
+	};
+}
+/**
+* Type guard to check if a value is a Preset.
+*
+* @param value - The value to check
+* @returns True if the value is a Preset, false otherwise
+*
+* @example
+* ```typescript
+* if (isPreset(value)) {
+*   console.log(value.atom, value.value)
+* }
+* ```
+*/
+function isPreset(value) {
+	return typeof value === "object" && value !== null && value[presetSymbol] === true;
+}
+
+//#endregion
+//#region src/scope.ts
+var ControllerImpl = class {
+	[controllerSymbol] = true;
+	constructor(atom$1, scope) {
+		this.atom = atom$1;
+		this.scope = scope;
+	}
+	get state() {
+		return this.scope.getEntry(this.atom)?.state ?? "idle";
+	}
+	get() {
+		const entry = this.scope.getEntry(this.atom);
+		if (!entry || entry.state === "idle") throw new Error("Atom not resolved");
+		if (entry.state === "failed" && entry.error) throw entry.error;
+		if (entry.state === "resolving" && entry.hasValue) return entry.value;
+		if (entry.state === "resolved" && entry.hasValue) return entry.value;
+		throw new Error("Atom not resolved");
+	}
+	async resolve() {
+		return this.scope.resolve(this.atom);
+	}
+	async release() {
+		return this.scope.release(this.atom);
+	}
+	invalidate() {
+		this.scope.invalidate(this.atom);
+	}
+	on(listener) {
+		return this.scope.addListener(this.atom, listener);
+	}
+};
+var ScopeImpl = class {
+	cache = /* @__PURE__ */ new Map();
+	presets = /* @__PURE__ */ new Map();
+	resolving = /* @__PURE__ */ new Set();
+	pending = /* @__PURE__ */ new Map();
+	stateListeners = /* @__PURE__ */ new Map();
+	invalidationQueue = /* @__PURE__ */ new Set();
+	invalidationScheduled = false;
+	extensions;
+	tags;
+	scheduleInvalidation(atom$1) {
+		this.invalidationQueue.add(atom$1);
+		if (!this.invalidationScheduled) {
+			this.invalidationScheduled = true;
+			queueMicrotask(() => this.flushInvalidations());
+		}
+	}
+	flushInvalidations() {
+		this.invalidationScheduled = false;
+		const atoms = [...this.invalidationQueue];
+		this.invalidationQueue.clear();
+		for (const atom$1 of atoms) this.invalidate(atom$1);
+	}
+	constructor(options) {
+		this.extensions = options?.extensions ?? [];
+		this.tags = options?.tags ?? [];
+		for (const p of options?.presets ?? []) this.presets.set(p.atom, p.value);
+	}
+	async init() {
+		for (const ext of this.extensions) if (ext.init) await ext.init(this);
+	}
+	getEntry(atom$1) {
+		return this.cache.get(atom$1);
+	}
+	getOrCreateEntry(atom$1) {
+		let entry = this.cache.get(atom$1);
+		if (!entry) {
+			entry = {
+				state: "idle",
+				hasValue: false,
+				cleanups: [],
+				listeners: /* @__PURE__ */ new Set(),
+				pendingInvalidate: false
+			};
+			this.cache.set(atom$1, entry);
+		}
+		return entry;
+	}
+	addListener(atom$1, listener) {
+		const entry = this.getOrCreateEntry(atom$1);
+		entry.listeners.add(listener);
+		return () => {
+			entry.listeners.delete(listener);
+		};
+	}
+	notifyListeners(atom$1) {
+		const entry = this.cache.get(atom$1);
+		if (entry) for (const listener of entry.listeners) listener();
+	}
+	emitStateChange(state, atom$1) {
+		const stateMap = this.stateListeners.get(state);
+		if (stateMap) {
+			const listeners = stateMap.get(atom$1);
+			if (listeners) for (const listener of listeners) listener();
+		}
+	}
+	on(event, atom$1, listener) {
+		let stateMap = this.stateListeners.get(event);
+		if (!stateMap) {
+			stateMap = /* @__PURE__ */ new Map();
+			this.stateListeners.set(event, stateMap);
+		}
+		let listeners = stateMap.get(atom$1);
+		if (!listeners) {
+			listeners = /* @__PURE__ */ new Set();
+			stateMap.set(atom$1, listeners);
+		}
+		listeners.add(listener);
+		const capturedStateMap = stateMap;
+		const capturedListeners = listeners;
+		return () => {
+			capturedListeners.delete(listener);
+			if (capturedListeners.size === 0) {
+				capturedStateMap.delete(atom$1);
+				if (capturedStateMap.size === 0) this.stateListeners.delete(event);
+			}
+		};
+	}
+	async resolve(atom$1) {
+		const entry = this.cache.get(atom$1);
+		if (entry?.state === "resolved") return entry.value;
+		const pendingPromise = this.pending.get(atom$1);
+		if (pendingPromise) return pendingPromise;
+		if (this.resolving.has(atom$1)) throw new Error("Circular dependency detected");
+		const presetValue = this.presets.get(atom$1);
+		if (presetValue !== void 0) {
+			if (isAtom(presetValue)) return this.resolve(presetValue);
+			const newEntry = this.getOrCreateEntry(atom$1);
+			newEntry.state = "resolved";
+			newEntry.value = presetValue;
+			newEntry.hasValue = true;
+			this.emitStateChange("resolved", atom$1);
+			this.notifyListeners(atom$1);
+			return newEntry.value;
+		}
+		this.resolving.add(atom$1);
+		const promise = this.doResolve(atom$1);
+		this.pending.set(atom$1, promise);
+		try {
+			return await promise;
+		} finally {
+			this.resolving.delete(atom$1);
+			this.pending.delete(atom$1);
+		}
+	}
+	async doResolve(atom$1) {
+		const entry = this.getOrCreateEntry(atom$1);
+		entry.state = "resolving";
+		this.emitStateChange("resolving", atom$1);
+		this.notifyListeners(atom$1);
+		const resolvedDeps = await this.resolveDeps(atom$1.deps);
+		const ctx = {
+			cleanup: (fn) => entry.cleanups.push(fn),
+			invalidate: () => {
+				this.scheduleInvalidation(atom$1);
+			},
+			scope: this
+		};
+		const factory = atom$1.factory;
+		const doResolve = async () => {
+			if (atom$1.deps && Object.keys(atom$1.deps).length > 0) return factory(ctx, resolvedDeps);
+			else return factory(ctx);
+		};
+		try {
+			const value = await this.applyResolveExtensions(atom$1, doResolve);
+			entry.state = "resolved";
+			entry.value = value;
+			entry.hasValue = true;
+			entry.error = void 0;
+			this.emitStateChange("resolved", atom$1);
+			this.notifyListeners(atom$1);
+			if (entry.pendingInvalidate) {
+				entry.pendingInvalidate = false;
+				this.scheduleInvalidation(atom$1);
+			}
+			return value;
+		} catch (err) {
+			entry.state = "failed";
+			entry.error = err instanceof Error ? err : new Error(String(err));
+			entry.value = void 0;
+			entry.hasValue = false;
+			this.emitStateChange("failed", atom$1);
+			this.notifyListeners(atom$1);
+			if (entry.pendingInvalidate) {
+				entry.pendingInvalidate = false;
+				this.scheduleInvalidation(atom$1);
+			}
+			throw entry.error;
+		}
+	}
+	async applyResolveExtensions(atom$1, 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);
+			}
+		}
+		return next();
+	}
+	async resolveDeps(deps, tagSource) {
+		if (!deps) return {};
+		const result = {};
+		const tags$1 = tagSource ?? this.tags;
+		for (const [key, dep] of Object.entries(deps)) if (isAtom(dep)) result[key] = await this.resolve(dep);
+		else if (isControllerDep(dep)) result[key] = new ControllerImpl(dep.atom, this);
+		else if (tagExecutorSymbol in dep) {
+			const tagExecutor = dep;
+			switch (tagExecutor.mode) {
+				case "required":
+					result[key] = tagExecutor.tag.get(tags$1);
+					break;
+				case "optional":
+					result[key] = tagExecutor.tag.find(tags$1);
+					break;
+				case "all":
+					result[key] = tagExecutor.tag.collect(tags$1);
+					break;
+			}
+		}
+		return result;
+	}
+	controller(atom$1) {
+		return new ControllerImpl(atom$1, this);
+	}
+	invalidate(atom$1) {
+		const entry = this.cache.get(atom$1);
+		if (!entry) return;
+		if (entry.state === "idle") return;
+		if (entry.state === "resolving") {
+			entry.pendingInvalidate = true;
+			return;
+		}
+		this.doInvalidate(atom$1, entry);
+	}
+	async doInvalidate(atom$1, entry) {
+		const previousValue = entry.value;
+		for (let i = entry.cleanups.length - 1; i >= 0; i--) {
+			const cleanup = entry.cleanups[i];
+			if (cleanup) await cleanup();
+		}
+		entry.cleanups = [];
+		entry.state = "resolving";
+		entry.value = previousValue;
+		entry.error = void 0;
+		entry.pendingInvalidate = false;
+		this.pending.delete(atom$1);
+		this.resolving.delete(atom$1);
+		this.emitStateChange("resolving", atom$1);
+		this.notifyListeners(atom$1);
+		this.resolve(atom$1).catch(() => {});
+	}
+	async release(atom$1) {
+		const entry = this.cache.get(atom$1);
+		if (!entry) return;
+		for (let i = entry.cleanups.length - 1; i >= 0; i--) {
+			const cleanup = entry.cleanups[i];
+			if (cleanup) await cleanup();
+		}
+		this.cache.delete(atom$1);
+	}
+	async dispose() {
+		for (const ext of this.extensions) if (ext.dispose) await ext.dispose(this);
+		const atoms = Array.from(this.cache.keys());
+		for (const atom$1 of atoms) await this.release(atom$1);
+	}
+	createContext(options) {
+		return new ExecutionContextImpl(this, options);
+	}
+};
+var ExecutionContextImpl = class {
+	cleanups = [];
+	closed = false;
+	_input = void 0;
+	baseTags;
+	constructor(scope, options) {
+		this.scope = scope;
+		const ctxTags = options?.tags;
+		this.baseTags = ctxTags?.length ? [...ctxTags, ...scope.tags] : scope.tags;
+	}
+	get input() {
+		return this._input;
+	}
+	async exec(options) {
+		if (this.closed) throw new Error("ExecutionContext is closed");
+		if ("flow" in options) return this.execFlow(options);
+		else return this.execFn(options);
+	}
+	async execFlow(options) {
+		const { flow: flow$1, input, tags: execTags } = options;
+		const allTags = (execTags?.length ?? 0) > 0 || (flow$1.tags?.length ?? 0) > 0 ? [
+			...execTags ?? [],
+			...this.baseTags,
+			...flow$1.tags ?? []
+		] : this.baseTags;
+		const resolvedDeps = await this.scope.resolveDeps(flow$1.deps, allTags);
+		this._input = input;
+		const factory = flow$1.factory;
+		const doExec = async () => {
+			if (flow$1.deps && Object.keys(flow$1.deps).length > 0) return factory(this, resolvedDeps);
+			else return factory(this);
+		};
+		return this.applyExecExtensions(flow$1, doExec);
+	}
+	execFn(options) {
+		const { fn, params } = options;
+		const doExec = () => Promise.resolve(fn(...params));
+		return this.applyExecExtensions(fn, doExec);
+	}
+	async applyExecExtensions(target, doExec) {
+		let next = doExec;
+		for (let i = this.scope.extensions.length - 1; i >= 0; i--) {
+			const ext = this.scope.extensions[i];
+			if (ext?.wrapExec) {
+				const currentNext = next;
+				next = ext.wrapExec.bind(ext, currentNext, target, this);
+			}
+		}
+		return next();
+	}
+	onClose(fn) {
+		this.cleanups.push(fn);
+	}
+	async close() {
+		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();
+		}
+	}
+};
+/**
+* Creates a DI container that manages Atom resolution, caching, and lifecycle.
+*
+* @param options - Optional configuration for extensions, presets, and tags
+* @returns A Promise that resolves to a Scope instance
+*
+* @example
+* ```typescript
+* const scope = await createScope({
+*   extensions: [loggingExtension],
+*   presets: [preset(dbAtom, testDb)]
+* })
+* const db = await scope.resolve(dbAtom)
+* ```
+*/
+async function createScope(options) {
+	const scope = new ScopeImpl(options);
+	await scope.init();
+	return scope;
+}
+
+//#endregion
+//#region src/index.ts
+const VERSION = "0.0.1";
+
+//#endregion
+exports.VERSION = VERSION;
+exports.atom = atom;
+exports.atomSymbol = atomSymbol;
+exports.controller = controller;
+exports.controllerDepSymbol = controllerDepSymbol;
+exports.controllerSymbol = controllerSymbol;
+exports.createScope = createScope;
+exports.flow = flow;
+exports.flowSymbol = flowSymbol;
+exports.isAtom = isAtom;
+exports.isControllerDep = isControllerDep;
+exports.isFlow = isFlow;
+exports.isPreset = isPreset;
+exports.isTag = isTag;
+exports.isTagExecutor = isTagExecutor;
+exports.isTagged = isTagged;
+exports.preset = preset;
+exports.presetSymbol = presetSymbol;
+exports.tag = tag;
+exports.tagExecutorSymbol = tagExecutorSymbol;
+exports.tagSymbol = tagSymbol;
+exports.taggedSymbol = taggedSymbol;
+exports.tags = tags;