@azghr/singlet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# singlet
+
+Deduplicate concurrent async calls. Same key → one in-flight promise. **Not a cache.**
+
+Zero dependencies · Zero runtime overhead · ESM + CJS · TypeScript · Node / browsers / Deno / Bun / edge
+
+## The problem
+
+The same async operation often fires many times at once:
+- Three components mount and each fetch `/users/42` → 3 HTTP requests
+- A webhook burst triggers five identical DB refreshes → 5 database queries
+- Two clicks race the same mutation → conflicting writes
+
+You get **N network calls, N database hits, and sometimes N conflicting writes** — for one answer.
+
+## The solution
+
+singlet solves **concurrent call deduplication** — not caching:
+
+```ts
+import singlet from "@azghr/singlet";
+
+const flight = singlet();
+
+// These 3 concurrent calls → 1 HTTP request:
+const [user1, user2, user3] = await Promise.all([
+  flight.run(`user:42`, () => fetch('/api/users/42').then(r => r.json())),
+  flight.run(`user:42`, () => fetch('/api/users/42').then(r => r.json())),
+  flight.run(`user:42`, () => fetch('/api/users/42').then(r => r.json()))
+]);
+
+// After settlement → key is forgotten (not a cache):
+const later = await flight.run(`user:42`, () => fetch('/api/users/42').then(r => r.json()));
+// This makes a fresh request
+```
+
+## How it works
+
+1. **First call** with key → starts the operation, stores promise in Map
+2. **Concurrent calls** with same key → receive the same promise, **don't start new operation**
+3. **After promise settles** → key is **deleted from Map** (no caching)
+4. **Next call** with same key → starts fresh operation (sequential calls are not deduplicated)
+
+## Install
+
+```sh
+npm install @azghr/singlet
+```
+
+## Quick start
+
+### 1. Core API
+
+```ts
+import singlet from "@azghr/singlet";
+
+const flight = singlet();
+
+async function getUser(id: string) {
+  return flight.run(`user:${id}`, () =>
+    fetch(`/api/users/${id}`).then(r => r.json())
+  );
+}
+
+// Concurrent calls → ONE fetch
+const [user1, user2, user3] = await Promise.all([
+  getUser("42"),
+  getUser("42"),
+  getUser("42")
+]);
+```
+
+### 2. Ergonomic API
+
+```ts
+import { wrap } from "@azghr/singlet";
+
+const fetchUser = wrap(
+  async (id: string) => fetch(`/api/users/${id}`).then(r => r.json()),
+  { keyFn: ([id]) => `user:${id}` }
+);
+
+// Automatic deduplication based on arguments
+const [user1, user2] = await Promise.all([
+  fetchUser("42"),
+  fetchUser("42") // Only ONE HTTP request
+]);
+```
+
+### 3. Shared instance
+
+```ts
+import { shared } from "@azghr/singlet";
+
+// Simple app-wide deduplication
+const config = await shared.run("app:config", loadConfig);
+```
+
+## Use
+
+### Core API: `singlet()`
+
+```ts
+import singlet from "@azghr/singlet";
+
+const flight = singlet();
+
+async function getUser(id: string) {
+  return flight.run(`user:${id}`, () =>
+    fetch(`/api/users/${id}`).then((r) => r.json())
+  );
+}
+
+// Fired concurrently → ONE fetch, three identical results:
+const [a, b, c] = await Promise.all([getUser("42"), getUser("42"), getUser("42")]);
+
+// Fired afterwards → a fresh fetch (singlet is not a cache):
+const later = await getUser("42");
+```
+
+### Ergonomic API: `wrap()`
+
+The `wrap()` function automatically deduplicates based on function arguments:
+
+```ts
+import { wrap } from "@azghr/singlet";
+
+const fetchUser = wrap(
+  async (id: string) => fetch(`/api/users/${id}`).then(r => r.json()),
+  { keyFn: ([id]) => `user:${id}` }
+);
+
+// These concurrent calls share ONE fetch:
+const [user1, user2] = await Promise.all([
+  fetchUser('42'),
+  fetchUser('42')
+]);
+```
+
+### Fixed-key deduplication: `wrapWithKey()`
+
+For single operations that shouldn't run concurrently:
+
+```ts
+import { wrapWithKey } from "@azghr/singlet";
+
+const loadConfig = wrapWithKey(
+  async () => fetch('/api/config').then(r => r.json()),
+  'app:config'
+);
+
+// Multiple components loading config concurrently → ONE fetch:
+const [config1, config2] = await Promise.all([
+  loadConfig(),
+  loadConfig()
+]);
+```
+
+### Shared instance
+
+A shared app-wide instance is available for simple use cases:
+
+```ts
+import { shared } from "@azghr/singlet";
+await shared.run("config", loadConfig);
+```
+
+## API
+
+### Core functions
+
+#### `singlet(): Singlet`
+
+Creates an isolated singlet instance with its own key namespace.
+
+```ts
+import singlet from "@azghr/singlet";
+
+const flight = singlet();
+const adminFlight = singlet(); // Separate namespace
+```
+
+#### `Singlet.run<T>(key: string, fn: () => T | Promise<T>): Promise<T>`
+
+If `key` is in flight, returns the existing promise without calling `fn`.
+Otherwise calls `fn`, shares its promise with concurrent callers, and forgets
+the key once it settles.
+
+- **Rejections are shared** — all concurrent callers get the same error
+- **Rejections are forgotten** — next call retries fresh
+- **Synchronous throws become rejections** — never escape to callers
+- **Type inference** — `T` is inferred from `fn`, no generics needed
+
+Keys are plain strings; you decide how to serialize:
+```ts
+flight.run(`user:${id}`, () => fetchUser(id));
+flight.run(`cache:${JSON.stringify(params)}`, () => query(params));
+```
+
+#### `Singlet.forget(key: string): boolean`
+
+Drops an in-flight key so the *next* `run` starts fresh. Callers already
+awaiting the old promise still receive its result. Returns `false` if the key
+wasn't in flight.
+
+```ts
+// Invalidate mid-flight, next call retries:
+flight.forget(`user:${userId}`);
+```
+
+#### `Singlet.isInFlight(key: string): boolean` · `Singlet.size: number`
+
+Introspection for tests, metrics, and debugging.
+
+```ts
+if (flight.isInFlight(`user:${id}`)) {
+  console.log(`Already fetching user ${id}`);
+}
+console.log(`${flight.size} operations in flight`);
+```
+
+### Ergonomic functions
+
+#### `wrap<TArgs, TResult>(fn: (...args: TArgs) => TResult | Promise<TResult>, options: WrapOptions<TArgs>): (...args: TArgs) => Promise<TResult>`
+
+Wraps a function to automatically deduplicate concurrent calls based on its arguments.
+
+```ts
+import { wrap } from "@azghr/singlet";
+
+const fetchUser = wrap(
+  async (id: string) => fetch(`/api/users/${id}`).then(r => r.json()),
+  {
+    keyFn: ([id]) => `user:${id}` // Extract key from arguments
+  }
+);
+```
+
+**WrapOptions:**
+- `keyFn: (args: TArgs) => string` — Extract deduplication key from function arguments
+- `singlet?: Singlet` — Optional shared singlet instance
+
+#### `wrapWithKey<TResult>(fn: () => TResult | Promise<TResult>, key: string, singlet?: Singlet): () => Promise<TResult>`
+
+Wraps a no-argument function with a fixed deduplication key.
+
+```ts
+import { wrapWithKey } from "@azghr/singlet";
+
+const loadConfig = wrapWithKey(
+  async () => fetch('/api/config').then(r => r.json()),
+  'app:config'
+);
+```
+
+### Shared instance
+
+#### `shared: Singlet`
+
+A shared app-wide instance for simple use cases.
+
+```ts
+import { shared } from "@azghr/singlet";
+await shared.run("config", loadConfig);
+```
+
+## Patterns & composition
+
+### Deduplication + caching
+
+Singlet prevents concurrent duplicate work; cache libraries store results.
+Compose them for complete deduplication:
+
+```ts
+import { wrap } from "@azghr/singlet";
+
+const cache = new Map<string, User>();
+
+const getUser = wrap(
+  async (id: string) => {
+    const hit = cache.get(id);
+    if (hit) return hit;
+
+    const user = await fetchUser(id);
+    cache.set(id, user);
+    return user;
+  },
+  { keyFn: ([id]) => `user:${id}` }
+);
+```
+
+### Deduplication + retries
+
+Singlet shares concurrent calls; retry libraries handle transient failures:
+
+```ts
+import { wrap } from "@azghr/singlet";
+import pRetry from "p-retry";
+
+const fetchWithRetry = wrap(
+  (url: string) => pRetry(() => fetch(url), { retries: 3 }),
+  { keyFn: ([url]) => url }
+);
+```
+
+### Framework integration
+
+Singlet is framework-agnostic. Integrate with any framework:
+
+```ts
+// React hook example
+import { wrap } from "@azghr/singlet";
+
+const useUser = (id: string) => {
+  const fetchUser = wrap(
+    async (userId: string) => fetch(`/api/users/${userId}`).then(r => r.json()),
+    { keyFn: ([userId]) => `user:${userId}` }
+  );
+
+  // Use in React, Vue, Svelte, etc.
+  const { data, loading } = useFetch(() => fetchUser(id));
+  return { user: data, loading };
+};
+```
+
+### Custom key strategies
+
+You control how keys are generated:
+
+```ts
+// Single argument
+wrap(fetchUser, { keyFn: ([id]) => `user:${id}` });
+
+// Multiple arguments
+wrap(fetchResource, {
+  keyFn: ([method, url, params]) => `${method}:${url}:${JSON.stringify(params)}`
+});
+
+// Complex objects
+wrap(searchUsers, {
+  keyFn: ([query]) => `search:${JSON.stringify(query)}`
+});
+```
+
+## TypeScript
+
+Written in strict TypeScript; ships bundled `.d.ts`. All functions infer types from your code:
+
+```ts
+// Type inference works automatically
+const result = await flight.run("key", () => 42); // inferred as Promise<number>
+const result = await flight.run("key", () => "hello"); // inferred as Promise<string>
+
+// Generic functions are fully inferred
+const fetchUser = async (id: string): Promise<User> => ({ id, name: "User" });
+const wrapped = wrap(fetchUser, { keyFn: ([id]) => id });
+// wrapped is inferred as (id: string) => Promise<User>
+```
+
+## Use cases
+
+- **API deduplication**: Prevent duplicate HTTP requests for the same data
+- **Database query coalescing**: Share query results across concurrent operations
+- **Cache loading**: Single fetch when multiple components need the same data
+- **Mutation deduplication**: Prevent duplicate POST/PUT/DELETE operations
+- **Configuration loading**: Ensure config/auth loads once at startup
+- **Webhook debouncing**: Handle duplicate webhook events gracefully
+- **Resource initialization**: Share expensive setup across concurrent requests
+
+## Non-goals
+
+By design, `singlet` focuses on one thing: deduplicating concurrent in-flight calls. These features are **explicitly out of scope**:
+
+- **Result caching/TTLs** — Use cache libraries (lru-cache, node-cache)
+- **Retries/backoff** — Use retry libraries (p-retry, retry)
+- **Timeouts** — Use timeout libraries (p-timeout, Promise.race)
+- **Batching/DataLoader** — Use batching libraries (dataloader, batch-promises)
+- **Framework adapters** — Compose with React/Vue/Angular hooks
+- **Non-string keys** — Serialize your own keys with `JSON.stringify()`
+
+If you need these features, compose singlet with specialized libraries.
+
+## Performance
+
+singlet has **zero runtime overhead**:
+
+- No dependencies
+- No binary size cost (~1.2 KB minified)
+- O(1) Map operations for key lookup/insert/delete
+- No shared rejections create unhandled promise noise
+- Automatic cleanup after promise settlement
+
+## Examples
+
+Run the interactive demo:
+
+```sh
+npm run demo
+```
+
+Or explore examples in `examples/demo.ts` covering:
+- Basic deduplication
+- No caching behavior
+- Different key independence
+- Ergonomic wrap() API
+- Fixed-key operations
+- Error handling
+- Shared instance usage
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,84 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => singlet_default,
+  shared: () => shared,
+  singlet: () => singlet,
+  wrap: () => wrap,
+  wrapWithKey: () => wrapWithKey
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/singlet.ts
+function singlet() {
+  const inflight = /* @__PURE__ */ new Map();
+  return {
+    run(key, fn) {
+      const existing = inflight.get(key);
+      if (existing !== void 0) {
+        return existing;
+      }
+      const promise = Promise.resolve().then(fn).finally(() => {
+        if (inflight.get(key) === promise) {
+          inflight.delete(key);
+        }
+      });
+      inflight.set(key, promise);
+      return promise;
+    },
+    forget(key) {
+      return inflight.delete(key);
+    },
+    isInFlight(key) {
+      return inflight.has(key);
+    },
+    get size() {
+      return inflight.size;
+    }
+  };
+}
+var shared = singlet();
+var singlet_default = singlet;
+
+// src/wrap.ts
+function wrap(fn, options) {
+  const instance = options.singlet ?? singlet();
+  return function(...args) {
+    const key = options.keyFn(args);
+    return instance.run(key, () => fn(...args));
+  };
+}
+function wrapWithKey(fn, key, singlet2) {
+  const options = { keyFn: () => key };
+  if (singlet2 !== void 0) {
+    options.singlet = singlet2;
+  }
+  return wrap(fn, options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  shared,
+  singlet,
+  wrap,
+  wrapWithKey
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/singlet.ts","../src/wrap.ts"],"sourcesContent":["/**\n * singlet — deduplicate concurrent async calls.\n *\n * Barrel export: re-exports all public API.\n * No logic here — see src/singlet.ts and src/wrap.ts for implementation.\n */\n\nexport type { Singlet } from \"./singlet.js\";\nexport { singlet, shared } from \"./singlet.js\";\nexport { default } from \"./singlet.js\";\n\nexport type { WrapOptions } from \"./wrap.js\";\nexport { wrap, wrapWithKey } from \"./wrap.js\";\n","/**\n * singlet — deduplicate concurrent async calls.\n *\n * Concurrent calls with the same key share ONE in-flight promise.\n * Once the promise settles, the key is forgotten. singlet is NOT a cache:\n * it stores nothing after completion. One job, done well.\n */\n\nexport interface Singlet {\n  /**\n   * Run `fn` under `key`. If a call with the same key is already in flight,\n   * the existing promise is returned and `fn` is NOT invoked.\n   */\n  run<T>(key: string, fn: () => T | Promise<T>): Promise<T>;\n\n  /**\n   * Drop an in-flight key so the NEXT call starts fresh.\n   * Callers already awaiting the old promise still receive its result.\n   * Returns true if a key was dropped.\n   */\n  forget(key: string): boolean;\n\n  /** Whether a call for `key` is currently in flight. */\n  isInFlight(key: string): boolean;\n\n  /** Number of distinct keys currently in flight. */\n  readonly size: number;\n}\n\n/**\n * Create an isolated singlet instance (its own key namespace).\n */\nexport function singlet(): Singlet {\n  const inflight = new Map<string, Promise<unknown>>();\n\n  return {\n    run<T>(key: string, fn: () => T | Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing !== undefined) {\n        return existing as Promise<T>;\n      }\n\n      // `fn` is invoked in a microtask via .then(), AFTER the map entry is\n      // set, so synchronous throws inside `fn` reject the shared promise\n      // instead of escaping to only the first caller. The key is forgotten\n      // in `finally`, which runs BEFORE the promise settles for consumers —\n      // so by the time any caller's `await` resolves, the key is already\n      // gone and a sequential call starts fresh (no caching, not even for\n      // one microtask). The identity check guards against `forget()` having\n      // replaced the entry with a newer promise for the same key.\n      const promise: Promise<T> = Promise.resolve()\n        .then(fn)\n        .finally(() => {\n          if (inflight.get(key) === promise) {\n            inflight.delete(key);\n          }\n        });\n\n      inflight.set(key, promise);\n      return promise;\n    },\n\n    forget(key: string): boolean {\n      return inflight.delete(key);\n    },\n\n    isInFlight(key: string): boolean {\n      return inflight.has(key);\n    },\n\n    get size(): number {\n      return inflight.size;\n    },\n  };\n}\n\n/**\n * Shared default instance — convenient for app-wide deduplication.\n * Prefer `singlet()` instances in libraries to avoid key collisions.\n */\nexport const shared: Singlet = singlet();\n\n// Default export for ESM compatibility\nexport default singlet;\n","/**\n * Ergonomic layer over singlet core.\n *\n * This module COMPOSES the core singlet functionality — it never duplicates logic.\n * See src/singlet.ts for the core implementation.\n */\n\nimport type { Singlet } from \"./singlet.js\";\nimport { singlet as createSinglet } from \"./singlet.js\";\n\n/**\n * Options for configuring a wrapped function.\n */\nexport interface WrapOptions<TArgs> {\n  /**\n   * Extract a deduplication key from function arguments.\n   * Return the same key for concurrent calls that should share one promise.\n   *\n   * @example\n   * ```ts\n   * // Dedupe by user ID:\n   * keyFn: ([id]) => `user:${id}`\n   *\n   * // Dedupe by multiple args:\n   * keyFn: ([method, url]) => `${method}:${url}`\n   * ```\n   */\n  keyFn: (args: TArgs) => string;\n\n  /**\n   * Optional singlet instance for this wrapped function.\n   * Defaults to a new isolated instance.\n   * Use this to share a singlet across multiple wrapped functions.\n   */\n  singlet?: Singlet;\n}\n\n/**\n * Wrap an async function to automatically deduplicate concurrent calls.\n *\n * @example\n * ```ts\n * import { wrap } from 'singlet';\n *\n * const fetchUser = wrap(\n *   async (id: string) => fetch(`/api/users/${id}`).then(r => r.json()),\n *   { keyFn: ([id]) => `user:${id}` }\n * );\n *\n * // These two concurrent calls share ONE fetch:\n * const [user1, user2] = await Promise.all([\n *   fetchUser('42'),\n *   fetchUser('42')\n * ]);\n * ```\n *\n * @param fn - The async function to wrap\n * @param options - Configuration for key extraction and singlet instance\n * @returns A wrapped function with automatic deduplication\n */\nexport function wrap<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => TResult | Promise<TResult>,\n  options: WrapOptions<TArgs>\n): (...args: TArgs) => Promise<TResult> {\n  const instance = options.singlet ?? createSinglet();\n\n  return function (...args: TArgs): Promise<TResult> {\n    const key = options.keyFn(args);\n    return instance.run(key, () => fn(...args));\n  };\n}\n\n/**\n * Wrap an async function with a simple key string (for single-operation functions).\n *\n * @example\n * ```ts\n * import { wrapWithKey } from 'singlet';\n *\n * const loadConfig = wrapWithKey(\n *   async () => fetch('/api/config').then(r => r.json()),\n *   'config'\n * );\n * ```\n *\n * @param fn - The async function to wrap\n * @param key - Fixed key for all calls to this function\n * @param singlet - Optional singlet instance\n * @returns A wrapped function with fixed-key deduplication\n */\nexport function wrapWithKey<TResult>(\n  fn: () => TResult | Promise<TResult>,\n  key: string,\n  singlet?: Singlet\n): () => Promise<TResult> {\n  const options: WrapOptions<[]> = { keyFn: () => key };\n  if (singlet !== undefined) {\n    options.singlet = singlet;\n  }\n  return wrap(fn, options);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgCO,SAAS,UAAmB;AACjC,QAAM,WAAW,oBAAI,IAA8B;AAEnD,SAAO;AAAA,IACL,IAAO,KAAa,IAAsC;AACxD,YAAM,WAAW,SAAS,IAAI,GAAG;AACjC,UAAI,aAAa,QAAW;AAC1B,eAAO;AAAA,MACT;AAUA,YAAM,UAAsB,QAAQ,QAAQ,EACzC,KAAK,EAAE,EACP,QAAQ,MAAM;AACb,YAAI,SAAS,IAAI,GAAG,MAAM,SAAS;AACjC,mBAAS,OAAO,GAAG;AAAA,QACrB;AAAA,MACF,CAAC;AAEH,eAAS,IAAI,KAAK,OAAO;AACzB,aAAO;AAAA,IACT;AAAA,IAEA,OAAO,KAAsB;AAC3B,aAAO,SAAS,OAAO,GAAG;AAAA,IAC5B;AAAA,IAEA,WAAW,KAAsB;AAC/B,aAAO,SAAS,IAAI,GAAG;AAAA,IACzB;AAAA,IAEA,IAAI,OAAe;AACjB,aAAO,SAAS;AAAA,IAClB;AAAA,EACF;AACF;AAMO,IAAM,SAAkB,QAAQ;AAGvC,IAAO,kBAAQ;;;ACvBR,SAAS,KACd,IACA,SACsC;AACtC,QAAM,WAAW,QAAQ,WAAW,QAAc;AAElD,SAAO,YAAa,MAA+B;AACjD,UAAM,MAAM,QAAQ,MAAM,IAAI;AAC9B,WAAO,SAAS,IAAI,KAAK,MAAM,GAAG,GAAG,IAAI,CAAC;AAAA,EAC5C;AACF;AAoBO,SAAS,YACd,IACA,KACAA,UACwB;AACxB,QAAM,UAA2B,EAAE,OAAO,MAAM,IAAI;AACpD,MAAIA,aAAY,QAAW;AACzB,YAAQ,UAAUA;AAAA,EACpB;AACA,SAAO,KAAK,IAAI,OAAO;AACzB;","names":["singlet"]}

package/dist/index.d.cts

@@ -0,0 +1,111 @@
+/**
+ * singlet — deduplicate concurrent async calls.
+ *
+ * Concurrent calls with the same key share ONE in-flight promise.
+ * Once the promise settles, the key is forgotten. singlet is NOT a cache:
+ * it stores nothing after completion. One job, done well.
+ */
+interface Singlet {
+    /**
+     * Run `fn` under `key`. If a call with the same key is already in flight,
+     * the existing promise is returned and `fn` is NOT invoked.
+     */
+    run<T>(key: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Drop an in-flight key so the NEXT call starts fresh.
+     * Callers already awaiting the old promise still receive its result.
+     * Returns true if a key was dropped.
+     */
+    forget(key: string): boolean;
+    /** Whether a call for `key` is currently in flight. */
+    isInFlight(key: string): boolean;
+    /** Number of distinct keys currently in flight. */
+    readonly size: number;
+}
+/**
+ * Create an isolated singlet instance (its own key namespace).
+ */
+declare function singlet(): Singlet;
+/**
+ * Shared default instance — convenient for app-wide deduplication.
+ * Prefer `singlet()` instances in libraries to avoid key collisions.
+ */
+declare const shared: Singlet;
+
+/**
+ * Ergonomic layer over singlet core.
+ *
+ * This module COMPOSES the core singlet functionality — it never duplicates logic.
+ * See src/singlet.ts for the core implementation.
+ */
+
+/**
+ * Options for configuring a wrapped function.
+ */
+interface WrapOptions<TArgs> {
+    /**
+     * Extract a deduplication key from function arguments.
+     * Return the same key for concurrent calls that should share one promise.
+     *
+     * @example
+     * ```ts
+     * // Dedupe by user ID:
+     * keyFn: ([id]) => `user:${id}`
+     *
+     * // Dedupe by multiple args:
+     * keyFn: ([method, url]) => `${method}:${url}`
+     * ```
+     */
+    keyFn: (args: TArgs) => string;
+    /**
+     * Optional singlet instance for this wrapped function.
+     * Defaults to a new isolated instance.
+     * Use this to share a singlet across multiple wrapped functions.
+     */
+    singlet?: Singlet;
+}
+/**
+ * Wrap an async function to automatically deduplicate concurrent calls.
+ *
+ * @example
+ * ```ts
+ * import { wrap } from 'singlet';
+ *
+ * const fetchUser = wrap(
+ *   async (id: string) => fetch(`/api/users/${id}`).then(r => r.json()),
+ *   { keyFn: ([id]) => `user:${id}` }
+ * );
+ *
+ * // These two concurrent calls share ONE fetch:
+ * const [user1, user2] = await Promise.all([
+ *   fetchUser('42'),
+ *   fetchUser('42')
+ * ]);
+ * ```
+ *
+ * @param fn - The async function to wrap
+ * @param options - Configuration for key extraction and singlet instance
+ * @returns A wrapped function with automatic deduplication
+ */
+declare function wrap<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult | Promise<TResult>, options: WrapOptions<TArgs>): (...args: TArgs) => Promise<TResult>;
+/**
+ * Wrap an async function with a simple key string (for single-operation functions).
+ *
+ * @example
+ * ```ts
+ * import { wrapWithKey } from 'singlet';
+ *
+ * const loadConfig = wrapWithKey(
+ *   async () => fetch('/api/config').then(r => r.json()),
+ *   'config'
+ * );
+ * ```
+ *
+ * @param fn - The async function to wrap
+ * @param key - Fixed key for all calls to this function
+ * @param singlet - Optional singlet instance
+ * @returns A wrapped function with fixed-key deduplication
+ */
+declare function wrapWithKey<TResult>(fn: () => TResult | Promise<TResult>, key: string, singlet?: Singlet): () => Promise<TResult>;
+
+export { type Singlet, type WrapOptions, singlet as default, shared, singlet, wrap, wrapWithKey };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * singlet — deduplicate concurrent async calls.
+ *
+ * Concurrent calls with the same key share ONE in-flight promise.
+ * Once the promise settles, the key is forgotten. singlet is NOT a cache:
+ * it stores nothing after completion. One job, done well.
+ */
+interface Singlet {
+    /**
+     * Run `fn` under `key`. If a call with the same key is already in flight,
+     * the existing promise is returned and `fn` is NOT invoked.
+     */
+    run<T>(key: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Drop an in-flight key so the NEXT call starts fresh.
+     * Callers already awaiting the old promise still receive its result.
+     * Returns true if a key was dropped.
+     */
+    forget(key: string): boolean;
+    /** Whether a call for `key` is currently in flight. */
+    isInFlight(key: string): boolean;
+    /** Number of distinct keys currently in flight. */
+    readonly size: number;
+}
+/**
+ * Create an isolated singlet instance (its own key namespace).
+ */
+declare function singlet(): Singlet;
+/**
+ * Shared default instance — convenient for app-wide deduplication.
+ * Prefer `singlet()` instances in libraries to avoid key collisions.
+ */
+declare const shared: Singlet;
+
+/**
+ * Ergonomic layer over singlet core.
+ *
+ * This module COMPOSES the core singlet functionality — it never duplicates logic.
+ * See src/singlet.ts for the core implementation.
+ */
+
+/**
+ * Options for configuring a wrapped function.
+ */
+interface WrapOptions<TArgs> {
+    /**
+     * Extract a deduplication key from function arguments.
+     * Return the same key for concurrent calls that should share one promise.
+     *
+     * @example
+     * ```ts
+     * // Dedupe by user ID:
+     * keyFn: ([id]) => `user:${id}`
+     *
+     * // Dedupe by multiple args:
+     * keyFn: ([method, url]) => `${method}:${url}`
+     * ```
+     */
+    keyFn: (args: TArgs) => string;
+    /**
+     * Optional singlet instance for this wrapped function.
+     * Defaults to a new isolated instance.
+     * Use this to share a singlet across multiple wrapped functions.
+     */
+    singlet?: Singlet;
+}
+/**
+ * Wrap an async function to automatically deduplicate concurrent calls.
+ *
+ * @example
+ * ```ts
+ * import { wrap } from 'singlet';
+ *
+ * const fetchUser = wrap(
+ *   async (id: string) => fetch(`/api/users/${id}`).then(r => r.json()),
+ *   { keyFn: ([id]) => `user:${id}` }
+ * );
+ *
+ * // These two concurrent calls share ONE fetch:
+ * const [user1, user2] = await Promise.all([
+ *   fetchUser('42'),
+ *   fetchUser('42')
+ * ]);
+ * ```
+ *
+ * @param fn - The async function to wrap
+ * @param options - Configuration for key extraction and singlet instance
+ * @returns A wrapped function with automatic deduplication
+ */
+declare function wrap<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult | Promise<TResult>, options: WrapOptions<TArgs>): (...args: TArgs) => Promise<TResult>;
+/**
+ * Wrap an async function with a simple key string (for single-operation functions).
+ *
+ * @example
+ * ```ts
+ * import { wrapWithKey } from 'singlet';
+ *
+ * const loadConfig = wrapWithKey(
+ *   async () => fetch('/api/config').then(r => r.json()),
+ *   'config'
+ * );
+ * ```
+ *
+ * @param fn - The async function to wrap
+ * @param key - Fixed key for all calls to this function
+ * @param singlet - Optional singlet instance
+ * @returns A wrapped function with fixed-key deduplication
+ */
+declare function wrapWithKey<TResult>(fn: () => TResult | Promise<TResult>, key: string, singlet?: Singlet): () => Promise<TResult>;
+
+export { type Singlet, type WrapOptions, singlet as default, shared, singlet, wrap, wrapWithKey };

package/dist/index.js

@@ -0,0 +1,54 @@
+// src/singlet.ts
+function singlet() {
+  const inflight = /* @__PURE__ */ new Map();
+  return {
+    run(key, fn) {
+      const existing = inflight.get(key);
+      if (existing !== void 0) {
+        return existing;
+      }
+      const promise = Promise.resolve().then(fn).finally(() => {
+        if (inflight.get(key) === promise) {
+          inflight.delete(key);
+        }
+      });
+      inflight.set(key, promise);
+      return promise;
+    },
+    forget(key) {
+      return inflight.delete(key);
+    },
+    isInFlight(key) {
+      return inflight.has(key);
+    },
+    get size() {
+      return inflight.size;
+    }
+  };
+}
+var shared = singlet();
+var singlet_default = singlet;
+
+// src/wrap.ts
+function wrap(fn, options) {
+  const instance = options.singlet ?? singlet();
+  return function(...args) {
+    const key = options.keyFn(args);
+    return instance.run(key, () => fn(...args));
+  };
+}
+function wrapWithKey(fn, key, singlet2) {
+  const options = { keyFn: () => key };
+  if (singlet2 !== void 0) {
+    options.singlet = singlet2;
+  }
+  return wrap(fn, options);
+}
+export {
+  singlet_default as default,
+  shared,
+  singlet,
+  wrap,
+  wrapWithKey
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/singlet.ts","../src/wrap.ts"],"sourcesContent":["/**\n * singlet — deduplicate concurrent async calls.\n *\n * Concurrent calls with the same key share ONE in-flight promise.\n * Once the promise settles, the key is forgotten. singlet is NOT a cache:\n * it stores nothing after completion. One job, done well.\n */\n\nexport interface Singlet {\n  /**\n   * Run `fn` under `key`. If a call with the same key is already in flight,\n   * the existing promise is returned and `fn` is NOT invoked.\n   */\n  run<T>(key: string, fn: () => T | Promise<T>): Promise<T>;\n\n  /**\n   * Drop an in-flight key so the NEXT call starts fresh.\n   * Callers already awaiting the old promise still receive its result.\n   * Returns true if a key was dropped.\n   */\n  forget(key: string): boolean;\n\n  /** Whether a call for `key` is currently in flight. */\n  isInFlight(key: string): boolean;\n\n  /** Number of distinct keys currently in flight. */\n  readonly size: number;\n}\n\n/**\n * Create an isolated singlet instance (its own key namespace).\n */\nexport function singlet(): Singlet {\n  const inflight = new Map<string, Promise<unknown>>();\n\n  return {\n    run<T>(key: string, fn: () => T | Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing !== undefined) {\n        return existing as Promise<T>;\n      }\n\n      // `fn` is invoked in a microtask via .then(), AFTER the map entry is\n      // set, so synchronous throws inside `fn` reject the shared promise\n      // instead of escaping to only the first caller. The key is forgotten\n      // in `finally`, which runs BEFORE the promise settles for consumers —\n      // so by the time any caller's `await` resolves, the key is already\n      // gone and a sequential call starts fresh (no caching, not even for\n      // one microtask). The identity check guards against `forget()` having\n      // replaced the entry with a newer promise for the same key.\n      const promise: Promise<T> = Promise.resolve()\n        .then(fn)\n        .finally(() => {\n          if (inflight.get(key) === promise) {\n            inflight.delete(key);\n          }\n        });\n\n      inflight.set(key, promise);\n      return promise;\n    },\n\n    forget(key: string): boolean {\n      return inflight.delete(key);\n    },\n\n    isInFlight(key: string): boolean {\n      return inflight.has(key);\n    },\n\n    get size(): number {\n      return inflight.size;\n    },\n  };\n}\n\n/**\n * Shared default instance — convenient for app-wide deduplication.\n * Prefer `singlet()` instances in libraries to avoid key collisions.\n */\nexport const shared: Singlet = singlet();\n\n// Default export for ESM compatibility\nexport default singlet;\n","/**\n * Ergonomic layer over singlet core.\n *\n * This module COMPOSES the core singlet functionality — it never duplicates logic.\n * See src/singlet.ts for the core implementation.\n */\n\nimport type { Singlet } from \"./singlet.js\";\nimport { singlet as createSinglet } from \"./singlet.js\";\n\n/**\n * Options for configuring a wrapped function.\n */\nexport interface WrapOptions<TArgs> {\n  /**\n   * Extract a deduplication key from function arguments.\n   * Return the same key for concurrent calls that should share one promise.\n   *\n   * @example\n   * ```ts\n   * // Dedupe by user ID:\n   * keyFn: ([id]) => `user:${id}`\n   *\n   * // Dedupe by multiple args:\n   * keyFn: ([method, url]) => `${method}:${url}`\n   * ```\n   */\n  keyFn: (args: TArgs) => string;\n\n  /**\n   * Optional singlet instance for this wrapped function.\n   * Defaults to a new isolated instance.\n   * Use this to share a singlet across multiple wrapped functions.\n   */\n  singlet?: Singlet;\n}\n\n/**\n * Wrap an async function to automatically deduplicate concurrent calls.\n *\n * @example\n * ```ts\n * import { wrap } from 'singlet';\n *\n * const fetchUser = wrap(\n *   async (id: string) => fetch(`/api/users/${id}`).then(r => r.json()),\n *   { keyFn: ([id]) => `user:${id}` }\n * );\n *\n * // These two concurrent calls share ONE fetch:\n * const [user1, user2] = await Promise.all([\n *   fetchUser('42'),\n *   fetchUser('42')\n * ]);\n * ```\n *\n * @param fn - The async function to wrap\n * @param options - Configuration for key extraction and singlet instance\n * @returns A wrapped function with automatic deduplication\n */\nexport function wrap<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => TResult | Promise<TResult>,\n  options: WrapOptions<TArgs>\n): (...args: TArgs) => Promise<TResult> {\n  const instance = options.singlet ?? createSinglet();\n\n  return function (...args: TArgs): Promise<TResult> {\n    const key = options.keyFn(args);\n    return instance.run(key, () => fn(...args));\n  };\n}\n\n/**\n * Wrap an async function with a simple key string (for single-operation functions).\n *\n * @example\n * ```ts\n * import { wrapWithKey } from 'singlet';\n *\n * const loadConfig = wrapWithKey(\n *   async () => fetch('/api/config').then(r => r.json()),\n *   'config'\n * );\n * ```\n *\n * @param fn - The async function to wrap\n * @param key - Fixed key for all calls to this function\n * @param singlet - Optional singlet instance\n * @returns A wrapped function with fixed-key deduplication\n */\nexport function wrapWithKey<TResult>(\n  fn: () => TResult | Promise<TResult>,\n  key: string,\n  singlet?: Singlet\n): () => Promise<TResult> {\n  const options: WrapOptions<[]> = { keyFn: () => key };\n  if (singlet !== undefined) {\n    options.singlet = singlet;\n  }\n  return wrap(fn, options);\n}\n"],"mappings":";AAgCO,SAAS,UAAmB;AACjC,QAAM,WAAW,oBAAI,IAA8B;AAEnD,SAAO;AAAA,IACL,IAAO,KAAa,IAAsC;AACxD,YAAM,WAAW,SAAS,IAAI,GAAG;AACjC,UAAI,aAAa,QAAW;AAC1B,eAAO;AAAA,MACT;AAUA,YAAM,UAAsB,QAAQ,QAAQ,EACzC,KAAK,EAAE,EACP,QAAQ,MAAM;AACb,YAAI,SAAS,IAAI,GAAG,MAAM,SAAS;AACjC,mBAAS,OAAO,GAAG;AAAA,QACrB;AAAA,MACF,CAAC;AAEH,eAAS,IAAI,KAAK,OAAO;AACzB,aAAO;AAAA,IACT;AAAA,IAEA,OAAO,KAAsB;AAC3B,aAAO,SAAS,OAAO,GAAG;AAAA,IAC5B;AAAA,IAEA,WAAW,KAAsB;AAC/B,aAAO,SAAS,IAAI,GAAG;AAAA,IACzB;AAAA,IAEA,IAAI,OAAe;AACjB,aAAO,SAAS;AAAA,IAClB;AAAA,EACF;AACF;AAMO,IAAM,SAAkB,QAAQ;AAGvC,IAAO,kBAAQ;;;ACvBR,SAAS,KACd,IACA,SACsC;AACtC,QAAM,WAAW,QAAQ,WAAW,QAAc;AAElD,SAAO,YAAa,MAA+B;AACjD,UAAM,MAAM,QAAQ,MAAM,IAAI;AAC9B,WAAO,SAAS,IAAI,KAAK,MAAM,GAAG,GAAG,IAAI,CAAC;AAAA,EAC5C;AACF;AAoBO,SAAS,YACd,IACA,KACAA,UACwB;AACxB,QAAM,UAA2B,EAAE,OAAO,MAAM,IAAI;AACpD,MAAIA,aAAY,QAAW;AACzB,YAAQ,UAAUA;AAAA,EACpB;AACA,SAAO,KAAK,IAAI,OAAO;AACzB;","names":["singlet"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@azghr/singlet",
+  "version": "0.1.0",
+  "description": "Deduplicate concurrent async calls: same key, one in-flight promise. Not a cache.",
+  "keywords": [
+    "singleflight",
+    "dedupe",
+    "deduplication",
+    "promise",
+    "async",
+    "concurrency",
+    "thundering-herd",
+    "request-coalescing",
+    "typescript",
+    "type-safe",
+    "isomorphic",
+    "in-flight"
+  ],
+  "license": "MIT",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/azghr/singlet.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --sourcemap --clean",
+    "demo": "tsx examples/demo.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test",
+    "check": "npm run typecheck && npm run lint && npm run test && npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.20.1",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
+  }
+}