wellcrafted 0.42.0 → 0.43.0

package/dist/function.d.ts

@@ -0,0 +1,36 @@
+//#region src/function.d.ts
+/**
+ * Run-at-most-once wrapper. Wrap `fn` so the first call invokes it and caches the result;
+ * every later call is a no-op that returns that same cached result. Arguments passed after
+ * the first call are ignored.
+ *
+ * Canonical use: an idempotent `[Symbol.dispose]` whose teardown is reachable from more than
+ * one path and must not run twice. `once` makes that guarantee declarative instead of a
+ * hand-rolled `let disposed` flag.
+ *
+ * This is for the pure "this function body runs at most once" case. A boolean that is ALSO
+ * read by other methods to short-circuit a dead object is a liveness flag, not a once-guard;
+ * keep that boolean, `once` does not replace it.
+ *
+ * @example
+ * ```ts
+ * import { once } from "wellcrafted/function";
+ *
+ * const init = once(() => expensiveSetup());
+ * init(); // runs expensiveSetup()
+ * init(); // returns the cached result, does not run again
+ * ```
+ *
+ * @example Idempotent disposal
+ * ```ts
+ * import { once } from "wellcrafted/function";
+ *
+ * const dispose = once(() => closeConnection());
+ * // safe to call from multiple teardown paths; closeConnection() runs at most once
+ * ```
+ */
+declare function once<TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+//# sourceMappingURL=function.d.ts.map
+//#endregion
+export { once };
+//# sourceMappingURL=function.d.ts.map

package/dist/function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function.d.ts","names":[],"sources":["../src/function.ts"],"sourcesContent":[],"mappings":";;AA8BA;;;;;;AAE8B;;;;;;;;;;;;;;;;;;;;;;;iBAFd,8DACD,UAAU,oBACZ,UAAU"}

package/dist/function.js

@@ -0,0 +1,46 @@
+//#region src/function.ts
+/**
+* Run-at-most-once wrapper. Wrap `fn` so the first call invokes it and caches the result;
+* every later call is a no-op that returns that same cached result. Arguments passed after
+* the first call are ignored.
+*
+* Canonical use: an idempotent `[Symbol.dispose]` whose teardown is reachable from more than
+* one path and must not run twice. `once` makes that guarantee declarative instead of a
+* hand-rolled `let disposed` flag.
+*
+* This is for the pure "this function body runs at most once" case. A boolean that is ALSO
+* read by other methods to short-circuit a dead object is a liveness flag, not a once-guard;
+* keep that boolean, `once` does not replace it.
+*
+* @example
+* ```ts
+* import { once } from "wellcrafted/function";
+*
+* const init = once(() => expensiveSetup());
+* init(); // runs expensiveSetup()
+* init(); // returns the cached result, does not run again
+* ```
+*
+* @example Idempotent disposal
+* ```ts
+* import { once } from "wellcrafted/function";
+*
+* const dispose = once(() => closeConnection());
+* // safe to call from multiple teardown paths; closeConnection() runs at most once
+* ```
+*/
+function once(fn) {
+	let called = false;
+	let result;
+	return (...args) => {
+		if (!called) {
+			called = true;
+			result = fn(...args);
+		}
+		return result;
+	};
+}
+
+//#endregion
+export { once };
+//# sourceMappingURL=function.js.map

package/dist/function.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function.js","names":["fn: (...args: TArgs) => TReturn","result: TReturn"],"sources":["../src/function.ts"],"sourcesContent":["/**\n * Run-at-most-once wrapper. Wrap `fn` so the first call invokes it and caches the result;\n * every later call is a no-op that returns that same cached result. Arguments passed after\n * the first call are ignored.\n *\n * Canonical use: an idempotent `[Symbol.dispose]` whose teardown is reachable from more than\n * one path and must not run twice. `once` makes that guarantee declarative instead of a\n * hand-rolled `let disposed` flag.\n *\n * This is for the pure \"this function body runs at most once\" case. A boolean that is ALSO\n * read by other methods to short-circuit a dead object is a liveness flag, not a once-guard;\n * keep that boolean, `once` does not replace it.\n *\n * @example\n * ```ts\n * import { once } from \"wellcrafted/function\";\n *\n * const init = once(() => expensiveSetup());\n * init(); // runs expensiveSetup()\n * init(); // returns the cached result, does not run again\n * ```\n *\n * @example Idempotent disposal\n * ```ts\n * import { once } from \"wellcrafted/function\";\n *\n * const dispose = once(() => closeConnection());\n * // safe to call from multiple teardown paths; closeConnection() runs at most once\n * ```\n */\nexport function once<TArgs extends readonly unknown[], TReturn>(\n\tfn: (...args: TArgs) => TReturn,\n): (...args: TArgs) => TReturn {\n\tlet called = false;\n\tlet result: TReturn;\n\treturn (...args: TArgs): TReturn => {\n\t\tif (!called) {\n\t\t\tcalled = true;\n\t\t\tresult = fn(...args);\n\t\t}\n\t\treturn result;\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,KACfA,IAC8B;CAC9B,IAAI,SAAS;CACb,IAAIC;AACJ,QAAO,CAAC,GAAG,SAAyB;AACnC,OAAK,QAAQ;AACZ,YAAS;AACT,YAAS,GAAG,GAAG,KAAK;EACpB;AACD,SAAO;CACP;AACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wellcrafted",
-	"version": "0.42.0",
+	"version": "0.43.0",
 	"description": "Delightful TypeScript patterns for elegant, type-safe applications",
 	"type": "module",
 	"files": [
@@ -29,6 +29,10 @@
 			"types": "./dist/brand.d.ts",
 			"import": "./dist/brand.js"
 		},
+		"./function": {
+			"types": "./dist/function.d.ts",
+			"import": "./dist/function.js"
+		},
 		"./query": {
 			"types": "./dist/query/index.d.ts",
 			"import": "./dist/query/index.js"