Add singleton helper function for lazy initialization of instances (#34)

* Add singleton helper function for lazy initialization of instances

* Update version to 4.9.0 and document addition of singleton helper function in CHANGELOG.md

* Refactor singleton helper function to improve instance management by using a boolean flag for instance existence, enhancing error handling for promise rejections.

Author: ogroppo

CHANGELOG.md

@@ -1,5 +1,11 @@
 # deverything
 
+## 4.9.0
+
+### Minor Changes
+
+- singleton
+
 ## 4.8.0
 
 ### Minor Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "deverything",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Everything you need for Dev",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

src/helpers/singleton.ts

@@ -0,0 +1,40 @@
+import { isPromise } from "../validators/isPromise";
+
+/**
+ * Creates a lazily-initialized singleton from a factory function.
+ * Works with both sync and async factories — the return type mirrors the factory's.
+ *
+ * For async factories, concurrent callers during initialization share the same
+ * in-flight promise rather than triggering multiple factory calls. If the promise
+ * rejects, the singleton resets so the next call retries.
+ */
+export const singleton = <Result>(factory: () => Result): (() => Result) => {
+  let hasInstance = false;
+  let instance!: Result;
+
+  return () => {
+    if (hasInstance) {
+      return instance;
+    }
+
+    const result = factory();
+
+    if (isPromise(result)) {
+      hasInstance = true;
+      instance = result.then(
+        (value) => value,
+        (error) => {
+          hasInstance = false;
+          throw error;
+        }
+      ) as Result;
+
+      return instance;
+    }
+
+    // not a promise
+    hasInstance = true;
+    instance = result;
+    return result;
+  };
+};