astatus 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# astatus
+
+Async status signal. No data, no fetch — just the stage.
+
+```js
+import astatus from "astatus";
+
+const AS = astatus();
+
+AS.pending();
+await fetchUser();
+await processData(); // however many steps
+AS.success(); // you decide when
+```
+
+Most async state libraries tie status to data or fetch logic. `astatus` doesn't.  
+It's a standalone signal you inject into any flow, at any point you choose.
+
+---
+
+## Install
+
+```bash
+npm install astatus
+```
+
+---
+
+## Usage
+
+```js
+import astatus, { STATUS } from "astatus";
+
+const loginAS = astatus({ name: "login" });
+
+// Inject status at the right moment
+loginAS.pending();
+const data = await fetchUser();
+await syncStore(data); // sync or async, as many steps as needed
+loginAS.success();
+
+// Read
+console.log(loginAS.status); // 'success'
+console.log(loginAS.isSuccess); // true
+```
+
+---
+
+## API
+
+> All examples use `const AS = astatus()` unless otherwise noted.
+
+### Create
+
+```js
+astatus({ name?, status? })
+```
+
+| Option   | Type     | Default     | Description         |
+| -------- | -------- | ----------- | ------------------- |
+| `name`   | `string` | `null`      | Name for debug logs |
+| `status` | `string` | `'initial'` | Initial status      |
+
+---
+
+### Inject
+
+```js
+AS.initial()
+AS.pending()
+AS.success()
+AS.failure(error?)      // optional error value
+AS.custom('uploading')  // any string outside built-in stages
+```
+
+---
+
+### Read
+
+```js
+AS.status; // 'initial' | 'pending' | 'success' | 'failure' | custom
+AS.error; // value passed to failure(), otherwise null
+AS.isInitial;
+AS.isPending;
+AS.isSuccess;
+AS.isFailure;
+AS.isCustom; // true if current status is not a built-in stage
+AS.isLocked;
+```
+
+---
+
+### Observe
+
+```js
+// All changes
+const unsub = AS.subscribe((curr, prev) => {
+  console.log(curr.status, prev.status)
+})
+
+// Specific status — triggers on both entry and exit
+const unwatch = AS.watch('success', (curr, prev) => { ... })
+AS.watch(['success', 'failure'], (curr, prev) => { ... })
+
+// Entry only — triggers once on transition into the status
+const unwatch = AS.when('success', (curr, prev) => { ... })
+
+// Cleanup
+unsub()
+unwatch()
+```
+
+---
+
+### Wait
+
+```js
+// As a timing gate — wait for the right moment, then continue
+await AS.wait();
+await AS.wait("success");
+
+// As a result — inspect what happened
+const { status, error, timeout, immediate } = await AS.wait();
+const result = await AS.wait(["success", "failure"], 15); // timeout in seconds
+```
+
+| Field       | Description                        |
+| ----------- | ---------------------------------- |
+| `status`    | Status at resolve time (snapshot)  |
+| `error`     | Error at resolve time              |
+| `timeout`   | `true` if timed out                |
+| `immediate` | `true` if already in target status |
+| `destroyed` | `true` if instance was destroyed   |
+
+---
+
+### Lock
+
+```js
+AS.lock(); // block all status changes
+AS.unlock(); // unblock
+```
+
+---
+
+### Reset / Destroy
+
+```js
+AS.reset(); // back to initial, clears lock
+AS.destroy(); // clears all listeners, blocks all further changes
+```
+
+---
+
+### STATUS constant
+
+```js
+import { STATUS } from "astatus";
+
+STATUS.INITIAL; // 'initial'
+STATUS.PENDING; // 'pending'
+STATUS.SUCCESS; // 'success'
+STATUS.FAILURE; // 'failure'
+```
+
+---
+
+## Notes
+
+- `subscribe` / `watch` / `when` return an unsubscribe function — call it to clean up.
+- `destroy()` clears all listeners at once. Useful on route change or component unmount.
+- Listener errors are caught and logged individually without breaking other listeners.
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,199 @@
+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, {
+  STATUS: () => STATUS,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var STATUS = Object.freeze({
+  INITIAL: "initial",
+  PENDING: "pending",
+  SUCCESS: "success",
+  FAILURE: "failure"
+});
+var astatus = (options = {}) => {
+  const { name = null } = options;
+  const _prefix = `[astatus${name ? `:${name}` : ""}]`;
+  const _builtinStatuses = new Set(Object.values(STATUS));
+  let _status = options.status ?? STATUS.INITIAL;
+  let _error = null;
+  let _locked = false;
+  let _destroyed = false;
+  const _listeners = /* @__PURE__ */ new Set();
+  const _notify = (prevStatus, prevError) => {
+    const curr = { status: _status, error: _error };
+    const prev = { status: prevStatus, error: prevError };
+    _listeners.forEach((fn) => {
+      try {
+        fn(curr, prev);
+      } catch (e) {
+        console.error(`${_prefix} subscriber error:`, e);
+      }
+    });
+  };
+  const _set = (newStatus, newError = null) => {
+    if (_locked || _destroyed) return;
+    if (_status === newStatus && _error === newError) return;
+    const prevStatus = _status;
+    const prevError = _error;
+    _status = newStatus;
+    _error = newError;
+    _notify(prevStatus, prevError);
+  };
+  const isInitial = () => _status === STATUS.INITIAL;
+  const isPending = () => _status === STATUS.PENDING;
+  const isSuccess = () => _status === STATUS.SUCCESS;
+  const isFailure = () => _status === STATUS.FAILURE;
+  const isCustom = () => !_builtinStatuses.has(_status);
+  const initial = () => _set(STATUS.INITIAL);
+  const pending = () => _set(STATUS.PENDING);
+  const success = () => _set(STATUS.SUCCESS);
+  const failure = (error = null) => _set(STATUS.FAILURE, error);
+  const custom = (type) => {
+    if (!type) {
+      console.error(`${_prefix} custom() requires a non-empty string`);
+      return;
+    }
+    _set(type);
+  };
+  const lock = () => {
+    _locked = true;
+  };
+  const unlock = () => {
+    _locked = false;
+  };
+  const subscribe = (fn) => {
+    if (_destroyed) return () => {
+    };
+    _listeners.add(fn);
+    return () => _listeners.delete(fn);
+  };
+  const watch = (types, fn) => {
+    const _types = Array.isArray(types) ? types : [types];
+    return subscribe((curr, prev) => {
+      if (_types.includes(curr.status) || _types.includes(prev.status))
+        fn(curr, prev);
+    });
+  };
+  const when = (type, fn) => {
+    return subscribe((curr, prev) => {
+      if (curr.status === type && prev.status !== type) fn(curr, prev);
+    });
+  };
+  const wait = (types = [STATUS.SUCCESS, STATUS.FAILURE], timeoutSec = 10) => {
+    const _types = typeof types === "string" ? [types] : types;
+    if (_destroyed) {
+      return Promise.resolve({
+        timeout: false,
+        immediate: true,
+        destroyed: true,
+        status: _status,
+        error: _error
+      });
+    }
+    return new Promise((resolve) => {
+      if (_types.includes(_status)) {
+        resolve({
+          timeout: false,
+          immediate: true,
+          status: _status,
+          error: _error
+        });
+        return;
+      }
+      let unsubscribe;
+      const timer = setTimeout(() => {
+        unsubscribe();
+        resolve({
+          timeout: true,
+          immediate: false,
+          status: _status,
+          error: _error
+        });
+      }, timeoutSec * 1e3);
+      unsubscribe = subscribe(({ status, error }) => {
+        if (_types.includes(status)) {
+          clearTimeout(timer);
+          unsubscribe();
+          resolve({
+            timeout: false,
+            immediate: false,
+            status,
+            error
+          });
+        }
+      });
+    });
+  };
+  const reset = () => {
+    if (_destroyed) return;
+    _locked = false;
+    _set(STATUS.INITIAL);
+  };
+  const destroy = () => {
+    _listeners.clear();
+    _destroyed = true;
+  };
+  return {
+    get status() {
+      return _status;
+    },
+    get error() {
+      return _error;
+    },
+    get isInitial() {
+      return isInitial();
+    },
+    get isPending() {
+      return isPending();
+    },
+    get isSuccess() {
+      return isSuccess();
+    },
+    get isFailure() {
+      return isFailure();
+    },
+    get isCustom() {
+      return isCustom();
+    },
+    get isLocked() {
+      return _locked;
+    },
+    initial,
+    pending,
+    success,
+    failure,
+    custom,
+    lock,
+    unlock,
+    subscribe,
+    watch,
+    when,
+    wait,
+    reset,
+    destroy
+  };
+};
+var index_default = astatus;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  STATUS
+});

package/dist/index.d.cts

@@ -0,0 +1,60 @@
+declare const STATUS: Readonly<{
+    readonly INITIAL: "initial";
+    readonly PENDING: "pending";
+    readonly SUCCESS: "success";
+    readonly FAILURE: "failure";
+}>;
+type StatusValue = (typeof STATUS)[keyof typeof STATUS];
+interface AstatusState {
+    status: string;
+    error: unknown;
+}
+type AstatusListener = (curr: AstatusState, prev: AstatusState) => void;
+interface AstatusOptions {
+    status?: string;
+    name?: string;
+}
+interface AstatusWaitResult {
+    timeout: boolean;
+    immediate: boolean;
+    destroyed?: boolean;
+    status: string;
+    error: unknown;
+}
+interface Astatus {
+    readonly status: string;
+    readonly error: unknown;
+    readonly isInitial: boolean;
+    readonly isPending: boolean;
+    readonly isSuccess: boolean;
+    readonly isFailure: boolean;
+    readonly isCustom: boolean;
+    readonly isLocked: boolean;
+    initial: () => void;
+    pending: () => void;
+    success: () => void;
+    failure: (error?: unknown) => void;
+    custom: (type: string) => void;
+    lock: () => void;
+    unlock: () => void;
+    subscribe: (fn: AstatusListener) => () => void;
+    watch: (types: string | string[], fn: AstatusListener) => () => void;
+    when: (type: string, fn: AstatusListener) => () => void;
+    wait: (types?: string | string[], timeoutSec?: number) => Promise<AstatusWaitResult>;
+    reset: () => void;
+    destroy: () => void;
+}
+/**
+ * astatus
+ *
+ * A signal that manages only the stage of an async operation
+ * (initial / pending / success / failure).
+ * Completely decoupled from data and fetch logic —
+ * you decide when and where to inject each status.
+ *
+ * @param options.status - Initial status (default: 'initial')
+ * @param options.name - Name for debug logs
+ */
+declare const astatus: (options?: AstatusOptions) => Astatus;
+
+export { type Astatus, type AstatusListener, type AstatusOptions, type AstatusState, type AstatusWaitResult, STATUS, type StatusValue, astatus as default };

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+declare const STATUS: Readonly<{
+    readonly INITIAL: "initial";
+    readonly PENDING: "pending";
+    readonly SUCCESS: "success";
+    readonly FAILURE: "failure";
+}>;
+type StatusValue = (typeof STATUS)[keyof typeof STATUS];
+interface AstatusState {
+    status: string;
+    error: unknown;
+}
+type AstatusListener = (curr: AstatusState, prev: AstatusState) => void;
+interface AstatusOptions {
+    status?: string;
+    name?: string;
+}
+interface AstatusWaitResult {
+    timeout: boolean;
+    immediate: boolean;
+    destroyed?: boolean;
+    status: string;
+    error: unknown;
+}
+interface Astatus {
+    readonly status: string;
+    readonly error: unknown;
+    readonly isInitial: boolean;
+    readonly isPending: boolean;
+    readonly isSuccess: boolean;
+    readonly isFailure: boolean;
+    readonly isCustom: boolean;
+    readonly isLocked: boolean;
+    initial: () => void;
+    pending: () => void;
+    success: () => void;
+    failure: (error?: unknown) => void;
+    custom: (type: string) => void;
+    lock: () => void;
+    unlock: () => void;
+    subscribe: (fn: AstatusListener) => () => void;
+    watch: (types: string | string[], fn: AstatusListener) => () => void;
+    when: (type: string, fn: AstatusListener) => () => void;
+    wait: (types?: string | string[], timeoutSec?: number) => Promise<AstatusWaitResult>;
+    reset: () => void;
+    destroy: () => void;
+}
+/**
+ * astatus
+ *
+ * A signal that manages only the stage of an async operation
+ * (initial / pending / success / failure).
+ * Completely decoupled from data and fetch logic —
+ * you decide when and where to inject each status.
+ *
+ * @param options.status - Initial status (default: 'initial')
+ * @param options.name - Name for debug logs
+ */
+declare const astatus: (options?: AstatusOptions) => Astatus;
+
+export { type Astatus, type AstatusListener, type AstatusOptions, type AstatusState, type AstatusWaitResult, STATUS, type StatusValue, astatus as default };

package/dist/index.js

@@ -0,0 +1,175 @@
+// src/index.ts
+var STATUS = Object.freeze({
+  INITIAL: "initial",
+  PENDING: "pending",
+  SUCCESS: "success",
+  FAILURE: "failure"
+});
+var astatus = (options = {}) => {
+  const { name = null } = options;
+  const _prefix = `[astatus${name ? `:${name}` : ""}]`;
+  const _builtinStatuses = new Set(Object.values(STATUS));
+  let _status = options.status ?? STATUS.INITIAL;
+  let _error = null;
+  let _locked = false;
+  let _destroyed = false;
+  const _listeners = /* @__PURE__ */ new Set();
+  const _notify = (prevStatus, prevError) => {
+    const curr = { status: _status, error: _error };
+    const prev = { status: prevStatus, error: prevError };
+    _listeners.forEach((fn) => {
+      try {
+        fn(curr, prev);
+      } catch (e) {
+        console.error(`${_prefix} subscriber error:`, e);
+      }
+    });
+  };
+  const _set = (newStatus, newError = null) => {
+    if (_locked || _destroyed) return;
+    if (_status === newStatus && _error === newError) return;
+    const prevStatus = _status;
+    const prevError = _error;
+    _status = newStatus;
+    _error = newError;
+    _notify(prevStatus, prevError);
+  };
+  const isInitial = () => _status === STATUS.INITIAL;
+  const isPending = () => _status === STATUS.PENDING;
+  const isSuccess = () => _status === STATUS.SUCCESS;
+  const isFailure = () => _status === STATUS.FAILURE;
+  const isCustom = () => !_builtinStatuses.has(_status);
+  const initial = () => _set(STATUS.INITIAL);
+  const pending = () => _set(STATUS.PENDING);
+  const success = () => _set(STATUS.SUCCESS);
+  const failure = (error = null) => _set(STATUS.FAILURE, error);
+  const custom = (type) => {
+    if (!type) {
+      console.error(`${_prefix} custom() requires a non-empty string`);
+      return;
+    }
+    _set(type);
+  };
+  const lock = () => {
+    _locked = true;
+  };
+  const unlock = () => {
+    _locked = false;
+  };
+  const subscribe = (fn) => {
+    if (_destroyed) return () => {
+    };
+    _listeners.add(fn);
+    return () => _listeners.delete(fn);
+  };
+  const watch = (types, fn) => {
+    const _types = Array.isArray(types) ? types : [types];
+    return subscribe((curr, prev) => {
+      if (_types.includes(curr.status) || _types.includes(prev.status))
+        fn(curr, prev);
+    });
+  };
+  const when = (type, fn) => {
+    return subscribe((curr, prev) => {
+      if (curr.status === type && prev.status !== type) fn(curr, prev);
+    });
+  };
+  const wait = (types = [STATUS.SUCCESS, STATUS.FAILURE], timeoutSec = 10) => {
+    const _types = typeof types === "string" ? [types] : types;
+    if (_destroyed) {
+      return Promise.resolve({
+        timeout: false,
+        immediate: true,
+        destroyed: true,
+        status: _status,
+        error: _error
+      });
+    }
+    return new Promise((resolve) => {
+      if (_types.includes(_status)) {
+        resolve({
+          timeout: false,
+          immediate: true,
+          status: _status,
+          error: _error
+        });
+        return;
+      }
+      let unsubscribe;
+      const timer = setTimeout(() => {
+        unsubscribe();
+        resolve({
+          timeout: true,
+          immediate: false,
+          status: _status,
+          error: _error
+        });
+      }, timeoutSec * 1e3);
+      unsubscribe = subscribe(({ status, error }) => {
+        if (_types.includes(status)) {
+          clearTimeout(timer);
+          unsubscribe();
+          resolve({
+            timeout: false,
+            immediate: false,
+            status,
+            error
+          });
+        }
+      });
+    });
+  };
+  const reset = () => {
+    if (_destroyed) return;
+    _locked = false;
+    _set(STATUS.INITIAL);
+  };
+  const destroy = () => {
+    _listeners.clear();
+    _destroyed = true;
+  };
+  return {
+    get status() {
+      return _status;
+    },
+    get error() {
+      return _error;
+    },
+    get isInitial() {
+      return isInitial();
+    },
+    get isPending() {
+      return isPending();
+    },
+    get isSuccess() {
+      return isSuccess();
+    },
+    get isFailure() {
+      return isFailure();
+    },
+    get isCustom() {
+      return isCustom();
+    },
+    get isLocked() {
+      return _locked;
+    },
+    initial,
+    pending,
+    success,
+    failure,
+    custom,
+    lock,
+    unlock,
+    subscribe,
+    watch,
+    when,
+    wait,
+    reset,
+    destroy
+  };
+};
+var index_default = astatus;
+export {
+  STATUS,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "astatus",
+    "version": "0.1.0",
+    "description": "Async status signal. No data, no fetch — just the stage.",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format esm,cjs --dts",
+        "test": "vitest"
+    },
+    "keywords": [
+        "async",
+        "status",
+        "state",
+        "signal",
+        "framework-agnostic"
+    ],
+    "license": "MIT",
+    "devDependencies": {
+        "tsup": "latest",
+        "typescript": "^5.9.3",
+        "vitest": "latest"
+    }
+}