habicron 0.2.0

package/dist/react/index.d.ts

@@ -0,0 +1,61 @@
+import { Schedule, HabitSummary } from '../core/index.js';
+export { Duration, Jitter, Period } from '../core/index.js';
+
+interface ReactControlFlags {
+    /** Fire once immediately on start (counts toward `counter`). */
+    immediate?: boolean;
+    /** Expose `pause`, `resume`, `reset`, `isActive` on the return value. */
+    controls?: boolean;
+    /** Random source in `[0, 1)`. Defaults to `Math.random`. */
+    random?: () => number;
+}
+/** A single inline schedule, or an explicit list of overlapping habits. */
+type UseHabitOptions = ReactControlFlags & (Schedule | {
+    habits: Schedule[];
+});
+interface HabitBase {
+    /** Total number of times the callback has fired. */
+    counter: number;
+    /** Earliest upcoming fire across all habits, or `null` when stopped. */
+    nextRun: Date | null;
+}
+interface HabitControls {
+    isActive: boolean;
+    pause: () => void;
+    resume: () => void;
+    /** Reset `counter` to 0 and, if active, restart all habits from now. */
+    reset: () => void;
+}
+/**
+ * Schedule a callback on randomized recurring intervals — a "habit" engine.
+ *
+ * Accurate by default (evenly spaced, anchored to start time, no drift).
+ * Add `jitter` to perturb each fire by a bounded random amount.
+ *
+ * The schedule is captured once when the component mounts; the callback is
+ * always read fresh, so closing over changing props is safe. Control members
+ * (`pause`/`resume`/`reset`/`isActive`) are returned only with `controls: true`
+ * — expressed via overloads, so the return type is exact with no casting.
+ *
+ * @example
+ * const { counter, nextRun, pause } = useHabit(act, {
+ *   controls: true,
+ *   every: '20s ~ 4s',
+ * })
+ */
+declare function useHabit(callback: () => void | Promise<void>, options: UseHabitOptions & {
+    controls: true;
+}): HabitBase & HabitControls;
+declare function useHabit(callback: () => void | Promise<void>, options: UseHabitOptions): HabitBase;
+/**
+ * Reactively list every registered habit (from `createHabit` / `useHabit`).
+ * Re-renders as habits are added, removed, or change state — a ready-made
+ * management view.
+ *
+ * @example
+ * const habits = useHabits() // [{ id, name, isActive, counter, nextRun }, …]
+ */
+declare function useHabits(): HabitSummary[];
+
+export { HabitSummary, Schedule, useHabit, useHabits };
+export type { HabitBase, HabitControls, ReactControlFlags, UseHabitOptions };

package/dist/react/index.mjs

@@ -0,0 +1 @@
+import{useRef as f,useState as m,useEffect as v,useCallback as b}from"react";import{createHabit as y,subscribeHabits as H,listHabits as x}from"../core/index.mjs";function S(i,n){const r=f(i);r.current=i;const a=JSON.stringify(n,(e,o)=>typeof o=="function"?void 0:o),u=f(n);u.current=n;const[s,t]=m({counter:0,isActive:!1,nextRun:null}),c=f(null);v(()=>{const e=y(async()=>r.current(),{...u.current,autoStart:!0});c.current=e;const o=()=>{t({counter:e.counter,isActive:e.isActive,nextRun:e.nextRun})},d=e.subscribe(o);return o(),()=>{d(),e.destroy(),c.current=null}},[a]);const p=b(()=>c.current?.pause(),[]),R=b(()=>c.current?.resume(),[]),A=b(()=>c.current?.reset(),[]),l={counter:s.counter,nextRun:s.nextRun};return n.controls?{...l,isActive:s.isActive,pause:p,resume:R,reset:A}:l}function g(){const[i,n]=m([]);return v(()=>{let r=[];const a=()=>{n(x().map(t=>({id:t.id,name:t.name,isActive:t.isActive,counter:t.counter,nextRun:t.nextRun})))},u=()=>{for(const t of r)t();r=x().map(t=>t.subscribe(a)),a()};u();const s=H(u);return()=>{s();for(const t of r)t()}},[]),i}export{S as useHabit,g as useHabits};

package/dist/vue/index.cjs

@@ -0,0 +1 @@
+"use strict";const vue=require("vue"),core_index=require("../core/index.cjs");function useHabit(r,s){const{controls:o=!1}=s,n=vue.ref(0),u=vue.ref(!1),e=vue.ref(null),t=core_index.createHabit(r,{...s,autoStart:typeof window<"u"}),i=()=>{n.value=t.counter,u.value=t.isActive,e.value=t.nextRun};i();const a=t.subscribe(i);vue.getCurrentScope()&&vue.onScopeDispose(()=>{a(),t.destroy()});const c={counter:vue.readonly(n),nextRun:vue.readonly(e)};return o?{...c,isActive:vue.readonly(u),pause:t.pause,resume:t.resume,reset:t.reset}:c}function useHabits(){const r=vue.ref([]);let s=[];const o=()=>{r.value=core_index.listHabits().map(e=>({id:e.id,name:e.name,isActive:e.isActive,counter:e.counter,nextRun:e.nextRun}))},n=()=>{for(const e of s)e();s=core_index.listHabits().map(e=>e.subscribe(o)),o()};n();const u=core_index.subscribeHabits(n);return vue.getCurrentScope()&&vue.onScopeDispose(()=>{u();for(const e of s)e()}),vue.readonly(r)}exports.useHabit=useHabit,exports.useHabits=useHabits;

package/dist/vue/index.d.cts

@@ -0,0 +1,84 @@
+import { Ref } from 'vue';
+import { Schedule } from '../core/index.cjs';
+export { Duration, HabitSummary, Jitter, Period } from '../core/index.cjs';
+
+/**
+ * habicron — Vue adapter.
+ *
+ * Wraps the core engine in Vue refs via `useHabit`.
+ */
+
+interface VueControlFlags {
+    /** Fire once immediately on start (counts toward `counter`). */
+    immediate?: boolean;
+    /** Expose `pause`, `resume`, `reset`, `isActive` on the return value. */
+    controls?: boolean;
+    /** Random source in `[0, 1)`. Defaults to `Math.random`. */
+    random?: () => number;
+}
+/** A single inline schedule, or an explicit list of overlapping habits. */
+type UseHabitOptions = VueControlFlags & (Schedule | {
+    habits: Schedule[];
+});
+interface HabitBase {
+    /** Total number of times the callback has fired. */
+    readonly counter: Readonly<Ref<number>>;
+    /** Earliest upcoming fire across all habits, or `null` when stopped. */
+    readonly nextRun: Readonly<Ref<Date | null>>;
+}
+interface HabitControls {
+    readonly isActive: Readonly<Ref<boolean>>;
+    pause: () => void;
+    resume: () => void;
+    /** Reset `counter` to 0 and, if active, restart all habits from now. */
+    reset: () => void;
+}
+/**
+ * Schedule a callback on randomized recurring intervals — a "habit" engine.
+ *
+ * Accurate by default (evenly spaced, anchored to start time, no drift).
+ * Add `jitter` to perturb each fire by a bounded random amount. Control members
+ * (`pause`/`resume`/`reset`/`isActive`) are returned only with `controls: true`
+ * — expressed via overloads, so the return type is exact with no casting.
+ *
+ * @example
+ * useHabit(act, { every: '2h ~ 5m' })
+ *
+ * @example
+ * const { counter, nextRun, pause } = useHabit(act, {
+ *   controls: true,
+ *   habits: [
+ *     { every: '20s', jitter: ['3s', '5s'] },
+ *     { times: 2, per: 'day', jitter: '2h' },
+ *   ],
+ * })
+ */
+declare function useHabit(callback: () => void | Promise<void>, options: UseHabitOptions & {
+    controls: true;
+}): HabitBase & HabitControls;
+declare function useHabit(callback: () => void | Promise<void>, options: UseHabitOptions): HabitBase;
+/**
+ * Reactively list every registered habit (from `createHabit` / `useHabit`).
+ * The returned ref updates as habits are added, removed, or change state —
+ * a ready-made management view.
+ *
+ * @example
+ * const habits = useHabits()
+ * // habits.value -> [{ id, name, isActive, counter, nextRun }, …]
+ */
+declare function useHabits(): Readonly<Ref<readonly {
+    readonly id: string;
+    readonly name: string | undefined;
+    readonly isActive: boolean;
+    readonly counter: number;
+    readonly nextRun: Date | null;
+}[], readonly {
+    readonly id: string;
+    readonly name: string | undefined;
+    readonly isActive: boolean;
+    readonly counter: number;
+    readonly nextRun: Date | null;
+}[]>>;
+
+export { Schedule, useHabit, useHabits };
+export type { HabitBase, HabitControls, UseHabitOptions, VueControlFlags };

package/dist/vue/index.d.mts

@@ -0,0 +1,84 @@
+import { Ref } from 'vue';
+import { Schedule } from '../core/index.mjs';
+export { Duration, HabitSummary, Jitter, Period } from '../core/index.mjs';
+
+/**
+ * habicron — Vue adapter.
+ *
+ * Wraps the core engine in Vue refs via `useHabit`.
+ */
+
+interface VueControlFlags {
+    /** Fire once immediately on start (counts toward `counter`). */
+    immediate?: boolean;
+    /** Expose `pause`, `resume`, `reset`, `isActive` on the return value. */
+    controls?: boolean;
+    /** Random source in `[0, 1)`. Defaults to `Math.random`. */
+    random?: () => number;
+}
+/** A single inline schedule, or an explicit list of overlapping habits. */
+type UseHabitOptions = VueControlFlags & (Schedule | {
+    habits: Schedule[];
+});
+interface HabitBase {
+    /** Total number of times the callback has fired. */
+    readonly counter: Readonly<Ref<number>>;
+    /** Earliest upcoming fire across all habits, or `null` when stopped. */
+    readonly nextRun: Readonly<Ref<Date | null>>;
+}
+interface HabitControls {
+    readonly isActive: Readonly<Ref<boolean>>;
+    pause: () => void;
+    resume: () => void;
+    /** Reset `counter` to 0 and, if active, restart all habits from now. */
+    reset: () => void;
+}
+/**
+ * Schedule a callback on randomized recurring intervals — a "habit" engine.
+ *
+ * Accurate by default (evenly spaced, anchored to start time, no drift).
+ * Add `jitter` to perturb each fire by a bounded random amount. Control members
+ * (`pause`/`resume`/`reset`/`isActive`) are returned only with `controls: true`
+ * — expressed via overloads, so the return type is exact with no casting.
+ *
+ * @example
+ * useHabit(act, { every: '2h ~ 5m' })
+ *
+ * @example
+ * const { counter, nextRun, pause } = useHabit(act, {
+ *   controls: true,
+ *   habits: [
+ *     { every: '20s', jitter: ['3s', '5s'] },
+ *     { times: 2, per: 'day', jitter: '2h' },
+ *   ],
+ * })
+ */
+declare function useHabit(callback: () => void | Promise<void>, options: UseHabitOptions & {
+    controls: true;
+}): HabitBase & HabitControls;
+declare function useHabit(callback: () => void | Promise<void>, options: UseHabitOptions): HabitBase;
+/**
+ * Reactively list every registered habit (from `createHabit` / `useHabit`).
+ * The returned ref updates as habits are added, removed, or change state —
+ * a ready-made management view.
+ *
+ * @example
+ * const habits = useHabits()
+ * // habits.value -> [{ id, name, isActive, counter, nextRun }, …]
+ */
+declare function useHabits(): Readonly<Ref<readonly {
+    readonly id: string;
+    readonly name: string | undefined;
+    readonly isActive: boolean;
+    readonly counter: number;
+    readonly nextRun: Date | null;
+}[], readonly {
+    readonly id: string;
+    readonly name: string | undefined;
+    readonly isActive: boolean;
+    readonly counter: number;
+    readonly nextRun: Date | null;
+}[]>>;
+
+export { Schedule, useHabit, useHabits };
+export type { HabitBase, HabitControls, UseHabitOptions, VueControlFlags };

package/dist/vue/index.d.ts

@@ -0,0 +1,84 @@
+import { Ref } from 'vue';
+import { Schedule } from '../core/index.js';
+export { Duration, HabitSummary, Jitter, Period } from '../core/index.js';
+
+/**
+ * habicron — Vue adapter.
+ *
+ * Wraps the core engine in Vue refs via `useHabit`.
+ */
+
+interface VueControlFlags {
+    /** Fire once immediately on start (counts toward `counter`). */
+    immediate?: boolean;
+    /** Expose `pause`, `resume`, `reset`, `isActive` on the return value. */
+    controls?: boolean;
+    /** Random source in `[0, 1)`. Defaults to `Math.random`. */
+    random?: () => number;
+}
+/** A single inline schedule, or an explicit list of overlapping habits. */
+type UseHabitOptions = VueControlFlags & (Schedule | {
+    habits: Schedule[];
+});
+interface HabitBase {
+    /** Total number of times the callback has fired. */
+    readonly counter: Readonly<Ref<number>>;
+    /** Earliest upcoming fire across all habits, or `null` when stopped. */
+    readonly nextRun: Readonly<Ref<Date | null>>;
+}
+interface HabitControls {
+    readonly isActive: Readonly<Ref<boolean>>;
+    pause: () => void;
+    resume: () => void;
+    /** Reset `counter` to 0 and, if active, restart all habits from now. */
+    reset: () => void;
+}
+/**
+ * Schedule a callback on randomized recurring intervals — a "habit" engine.
+ *
+ * Accurate by default (evenly spaced, anchored to start time, no drift).
+ * Add `jitter` to perturb each fire by a bounded random amount. Control members
+ * (`pause`/`resume`/`reset`/`isActive`) are returned only with `controls: true`
+ * — expressed via overloads, so the return type is exact with no casting.
+ *
+ * @example
+ * useHabit(act, { every: '2h ~ 5m' })
+ *
+ * @example
+ * const { counter, nextRun, pause } = useHabit(act, {
+ *   controls: true,
+ *   habits: [
+ *     { every: '20s', jitter: ['3s', '5s'] },
+ *     { times: 2, per: 'day', jitter: '2h' },
+ *   ],
+ * })
+ */
+declare function useHabit(callback: () => void | Promise<void>, options: UseHabitOptions & {
+    controls: true;
+}): HabitBase & HabitControls;
+declare function useHabit(callback: () => void | Promise<void>, options: UseHabitOptions): HabitBase;
+/**
+ * Reactively list every registered habit (from `createHabit` / `useHabit`).
+ * The returned ref updates as habits are added, removed, or change state —
+ * a ready-made management view.
+ *
+ * @example
+ * const habits = useHabits()
+ * // habits.value -> [{ id, name, isActive, counter, nextRun }, …]
+ */
+declare function useHabits(): Readonly<Ref<readonly {
+    readonly id: string;
+    readonly name: string | undefined;
+    readonly isActive: boolean;
+    readonly counter: number;
+    readonly nextRun: Date | null;
+}[], readonly {
+    readonly id: string;
+    readonly name: string | undefined;
+    readonly isActive: boolean;
+    readonly counter: number;
+    readonly nextRun: Date | null;
+}[]>>;
+
+export { Schedule, useHabit, useHabits };
+export type { HabitBase, HabitControls, UseHabitOptions, VueControlFlags };

package/dist/vue/index.mjs

@@ -0,0 +1 @@
+import{ref as i,getCurrentScope as m,onScopeDispose as p,readonly as c}from"vue";import{createHabit as v,subscribeHabits as d,listHabits as f}from"../core/index.mjs";function x(o,n){const{controls:r=!1}=n,s=i(0),u=i(!1),e=i(null),t=v(o,{...n,autoStart:typeof window<"u"}),a=()=>{s.value=t.counter,u.value=t.isActive,e.value=t.nextRun};a();const l=t.subscribe(a);m()&&p(()=>{l(),t.destroy()});const b={counter:c(s),nextRun:c(e)};return r?{...b,isActive:c(u),pause:t.pause,resume:t.resume,reset:t.reset}:b}function H(){const o=i([]);let n=[];const r=()=>{o.value=f().map(e=>({id:e.id,name:e.name,isActive:e.isActive,counter:e.counter,nextRun:e.nextRun}))},s=()=>{for(const e of n)e();n=f().map(e=>e.subscribe(r)),r()};s();const u=d(s);return m()&&p(()=>{u();for(const e of n)e()}),c(o)}export{x as useHabit,H as useHabits};

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "habicron",
+  "type": "module",
+  "version": "0.2.0",
+  "description": "Schedule callbacks on randomized recurring intervals — habits, not cronjobs. Accurate by default, jittered on demand, with no drift. Works in Node, Vue, React, and the CLI.",
+  "author": "thecodeorigin <nguyenhuunguyeny.ny@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/imrim12/habicron#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imrim12/habicron.git"
+  },
+  "bugs": {
+    "url": "https://github.com/imrim12/habicron/issues"
+  },
+  "keywords": [
+    "cron",
+    "cronjob",
+    "scheduler",
+    "schedule",
+    "interval",
+    "setInterval",
+    "jitter",
+    "random",
+    "habit",
+    "recurring",
+    "timer",
+    "vue",
+    "react",
+    "composable",
+    "hook",
+    "cli"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.mjs",
+      "require": "./dist/node/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.mjs",
+      "require": "./dist/core/index.cjs"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.mjs",
+      "require": "./dist/browser/index.cjs"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.mjs",
+      "require": "./dist/node/index.cjs"
+    },
+    "./vue": {
+      "types": "./dist/vue/index.d.ts",
+      "import": "./dist/vue/index.mjs",
+      "require": "./dist/vue/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.mjs",
+      "require": "./dist/react/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/node/index.cjs",
+  "module": "./dist/node/index.mjs",
+  "types": "./dist/node/index.d.ts",
+  "bin": {
+    "habit": "./dist/cli/index.mjs"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "vue": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.0.0",
+    "@eslint-react/eslint-plugin": "^5.9.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^10.5.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.3",
+    "eslint-plugin-vue": "^10.9.2",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.2",
+    "unbuild": "^2.0.0",
+    "vitest": "^2.1.8",
+    "vue": "^3.5.13",
+    "vue-eslint-parser": "^10.4.1"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}