@forthtilliath/ts-kit 0.14.0 → 0.15.0

package/README.md

@@ -68,6 +68,8 @@ Importing them is harmless anywhere: the DOM is only touched when called.
 - `rankByNameMatch(items, query, getName)` — ranks `items` by relevance to
   `query`: earlier match position first, then shorter name — for a
   search-as-you-type list.
+- `pickRandom(array, random?)` — one element picked at random, or
+  `undefined` for an empty array; same `random` as `shuffle`.
 - `shuffle(array, random?)` — shuffled copy (Fisher–Yates); `random`
   (default `Math.random`) can be swapped for a seeded generator in tests.
 - `sortUpcomingFirst(items, getDates, { now? })` — upcoming items first
@@ -266,6 +268,22 @@ Building blocks for writing an iCalendar (`.ics`, RFC 5545) file.
 - `deepEqual(a, b)` — recursive structural equality check.
 - `mapValues(obj, fn)` — maps every value of an object through `fn`.
 
+### `security`
+
+- `createAttemptLimiter({ storage, key, freeAttempts?, delaysMs?, now? })` —
+  growing delays between attempts at a secret (a PIN…): 4 free failures,
+  then 30 s, 1 min, 5 min, 15 min for each one after. `attempt(verify)`
+  returns `{ ok: true }` or `{ ok: false, lockedUntil }` (0 when no delay
+  is running) and doesn't call `verify` while locked; `getLockedUntil()`,
+  `reset()`. The counter lives in the injected `storage` (e.g.
+  expo-secure-store's `getItemAsync`/`setItemAsync`/`deleteItemAsync`); an
+  unreadable or tampered value counts as used up, not as zero, a clock set
+  back restarts the delay from now, and parallel attempts are serialized.
+  Limit: the delay is measured with the device clock, so setting it forward
+  ends the wait early — the failure count still grows, and each new failure
+  imposes the longest delay again. Keep the secret itself out of reach
+  (stored hashed, in the Android Keystore through expo-secure-store).
+
 ### `string`
 
 - `capitalize(str)` — uppercases the first letter, lowercases the rest.

package/dist/array/index.d.ts

@@ -5,6 +5,7 @@ export * from "./getMostRecentIds.js";
 export * from "./indexById.js";
 export * from "./moveItem.js";
 export * from "./nextInCycle.js";
+export * from "./pickRandom.js";
 export * from "./rankByNameMatch.js";
 export * from "./shuffle.js";
 export * from "./sortUpcomingFirst.js";

package/dist/array/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}

package/dist/array/index.js

@@ -5,6 +5,7 @@ export * from "./getMostRecentIds.js";
 export * from "./indexById.js";
 export * from "./moveItem.js";
 export * from "./nextInCycle.js";
+export * from "./pickRandom.js";
 export * from "./rankByNameMatch.js";
 export * from "./shuffle.js";
 export * from "./sortUpcomingFirst.js";

package/dist/array/pickRandom.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns one element of an array, picked at random (each equally likely).
+ *
+ * @param array - The array to pick from.
+ * @param random - Returns a number in `[0, 1)`. Defaults to `Math.random`;
+ * pass a seeded generator for deterministic tests.
+ * @returns The picked element, or `undefined` if `array` is empty.
+ * @example
+ * pickRandom(["rock", "paper", "scissors"]); // => e.g. "paper"
+ * pickRandom([1, 2, 3], () => 0.99); // => 3
+ * pickRandom([]); // => undefined
+ */
+export declare function pickRandom<T>(array: readonly T[], random?: () => number): T | undefined;
+//# sourceMappingURL=pickRandom.d.ts.map

package/dist/array/pickRandom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pickRandom.d.ts","sourceRoot":"","sources":["../../src/array/pickRandom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,GAAE,MAAM,MAAoB,GACjC,CAAC,GAAG,SAAS,CAEf"}

package/dist/array/pickRandom.js

@@ -0,0 +1,15 @@
+/**
+ * Returns one element of an array, picked at random (each equally likely).
+ *
+ * @param array - The array to pick from.
+ * @param random - Returns a number in `[0, 1)`. Defaults to `Math.random`;
+ * pass a seeded generator for deterministic tests.
+ * @returns The picked element, or `undefined` if `array` is empty.
+ * @example
+ * pickRandom(["rock", "paper", "scissors"]); // => e.g. "paper"
+ * pickRandom([1, 2, 3], () => 0.99); // => 3
+ * pickRandom([]); // => undefined
+ */
+export function pickRandom(array, random = Math.random) {
+    return array[Math.floor(random() * array.length)];
+}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from "./image/index.js";
 export * from "./markdown/index.js";
 export * from "./number/index.js";
 export * from "./object/index.js";
+export * from "./security/index.js";
 export * from "./string/index.js";
 export * from "./version/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -17,5 +17,6 @@ export * from "./image/index.js";
 export * from "./markdown/index.js";
 export * from "./number/index.js";
 export * from "./object/index.js";
+export * from "./security/index.js";
 export * from "./string/index.js";
 export * from "./version/index.js";

package/dist/security/createAttemptLimiter.d.ts

@@ -0,0 +1,65 @@
+/** Where the failure counter is kept — e.g. expo-secure-store on Android. */
+export interface AttemptLimiterStorage {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    deleteItem: (key: string) => Promise<void>;
+}
+export interface AttemptLimiterOptions {
+    storage: AttemptLimiterStorage;
+    /** Storage key of the failure counter. */
+    key: string;
+    /** Failures allowed before any delay. @defaultValue 4 */
+    freeAttempts?: number;
+    /**
+     * Delay imposed after the first failure past `freeAttempts`, the second…
+     * the last one repeating for every failure after.
+     * @defaultValue 30 s, 1 min, 5 min, 15 min
+     */
+    delaysMs?: readonly number[];
+    /** @defaultValue `Date.now` */
+    now?: () => number;
+}
+export type AttemptResult = {
+    ok: true;
+} | {
+    ok: false;
+    lockedUntil: number;
+};
+export interface AttemptLimiter {
+    /**
+     * Runs `verify` (e.g. compares a PIN) unless a delay is running, and
+     * updates the counter: reset on success, one more failure otherwise.
+     * `lockedUntil` is the end of the delay now imposed (0 for none). Attempts
+     * run one at a time, so parallel ones can't lose a failure.
+     */
+    attempt: (verify: () => boolean | Promise<boolean>) => Promise<AttemptResult>;
+    /** End of the running delay (a timestamp), or 0 if an attempt is allowed. */
+    getLockedUntil: () => Promise<number>;
+    /** Forgets every failure (e.g. once the PIN is reset another way). */
+    reset: () => Promise<void>;
+    /** The delay imposed after `count` consecutive failures (0 for none). */
+    delayAfter: (count: number) => number;
+}
+/**
+ * Limits attempts at a secret (a PIN, a passphrase) with growing delays:
+ * after `freeAttempts` failures, each new one imposes a wait. The counter is
+ * persisted through `storage`, so closing the app doesn't reset it, and an
+ * unreadable value is never taken as "no failure" (tampering with it would
+ * otherwise lift the limit): the next failure is then delayed at once. A
+ * last failure dated in the future (the clock was set back) restarts the
+ * delay from now instead of locking until that date.
+ *
+ * @example
+ * const pinLock = createAttemptLimiter({
+ *   storage: {
+ *     getItem: SecureStore.getItemAsync,
+ *     setItem: SecureStore.setItemAsync,
+ *     deleteItem: SecureStore.deleteItemAsync,
+ *   },
+ *   key: "pin-failures",
+ * });
+ * const result = await pinLock.attempt(() => isPinCorrect(typedPin));
+ * if (!result.ok && result.lockedUntil) showWaitUntil(result.lockedUntil);
+ */
+export declare function createAttemptLimiter({ storage, key, freeAttempts, delaysMs, now, }: AttemptLimiterOptions): AttemptLimiter;
+//# sourceMappingURL=createAttemptLimiter.d.ts.map

package/dist/security/createAttemptLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAttemptLimiter.d.ts","sourceRoot":"","sources":["../../src/security/createAttemptLimiter.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACjD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9E,6EAA6E;IAC7E,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,sEAAsE;IACtE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,yEAAyE;IACzE,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACvC;AAUD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,OAAO,EACP,GAAG,EACH,YAAgB,EAChB,QAA4B,EAC5B,GAAc,GACf,EAAE,qBAAqB,GAAG,cAAc,CA6ExC"}

package/dist/security/createAttemptLimiter.js

@@ -0,0 +1,96 @@
+const DEFAULT_DELAYS_MS = [30_000, 60_000, 5 * 60_000, 15 * 60_000];
+const MAX_COUNT = 1_000_000;
+/**
+ * Limits attempts at a secret (a PIN, a passphrase) with growing delays:
+ * after `freeAttempts` failures, each new one imposes a wait. The counter is
+ * persisted through `storage`, so closing the app doesn't reset it, and an
+ * unreadable value is never taken as "no failure" (tampering with it would
+ * otherwise lift the limit): the next failure is then delayed at once. A
+ * last failure dated in the future (the clock was set back) restarts the
+ * delay from now instead of locking until that date.
+ *
+ * @example
+ * const pinLock = createAttemptLimiter({
+ *   storage: {
+ *     getItem: SecureStore.getItemAsync,
+ *     setItem: SecureStore.setItemAsync,
+ *     deleteItem: SecureStore.deleteItemAsync,
+ *   },
+ *   key: "pin-failures",
+ * });
+ * const result = await pinLock.attempt(() => isPinCorrect(typedPin));
+ * if (!result.ok && result.lockedUntil) showWaitUntil(result.lockedUntil);
+ */
+export function createAttemptLimiter({ storage, key, freeAttempts = 4, delaysMs = DEFAULT_DELAYS_MS, now = Date.now, }) {
+    let queue = Promise.resolve();
+    function delayAfter(count) {
+        if (count <= freeAttempts || delaysMs.length === 0)
+            return 0;
+        const index = Math.min(count - freeAttempts - 1, delaysMs.length - 1);
+        return delaysMs[index] ?? 0;
+    }
+    async function readFailures() {
+        const raw = await storage.getItem(key);
+        if (raw === null || raw === "")
+            return { count: 0, lastFailureAt: 0 };
+        try {
+            const { count, lastFailureAt } = JSON.parse(raw);
+            if (typeof count === "number" &&
+                Number.isInteger(count) &&
+                count >= 0 &&
+                count <= MAX_COUNT &&
+                typeof lastFailureAt === "number" &&
+                Number.isFinite(lastFailureAt) &&
+                lastFailureAt >= 0) {
+                return { count, lastFailureAt };
+            }
+        }
+        catch {
+            // Unreadable: handled below.
+        }
+        return { count: freeAttempts, lastFailureAt: 0 };
+    }
+    async function writeFailures(failures) {
+        await storage.setItem(key, JSON.stringify(failures));
+    }
+    async function lockedUntil() {
+        const failures = await readFailures();
+        const current = now();
+        if (failures.lastFailureAt > current) {
+            failures.lastFailureAt = current;
+            await writeFailures(failures);
+        }
+        const until = failures.lastFailureAt + delayAfter(failures.count);
+        return until > current ? until : 0;
+    }
+    function serialized(task) {
+        const run = queue.then(task, task);
+        queue = run.catch(() => undefined);
+        return run;
+    }
+    return {
+        delayAfter,
+        getLockedUntil: () => serialized(lockedUntil),
+        reset: () => serialized(() => storage.deleteItem(key)),
+        attempt: (verify) => serialized(async () => {
+            const locked = await lockedUntil();
+            if (locked)
+                return { ok: false, lockedUntil: locked };
+            if (await verify()) {
+                await storage.deleteItem(key);
+                return { ok: true };
+            }
+            const { count } = await readFailures();
+            const failures = {
+                count: Math.min(count + 1, MAX_COUNT),
+                lastFailureAt: now(),
+            };
+            await writeFailures(failures);
+            const delay = delayAfter(failures.count);
+            return {
+                ok: false,
+                lockedUntil: delay ? failures.lastFailureAt + delay : 0,
+            };
+        }),
+    };
+}

package/dist/security/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./createAttemptLimiter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC"}

package/dist/security/index.js

@@ -0,0 +1 @@
+export * from "./createAttemptLimiter.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/ts-kit",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -22,13 +22,13 @@
     "./*": "./dist/*.js"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "5.0.2",
+    "@vitest/coverage-v8": "5.0.5",
     "eslint": "10.7.0",
     "jsdom": "^30.1.1",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.2",
-    "@forthtilliath/typescript-config": "0.1.1",
-    "@forthtilliath/eslint-config": "0.9.0"
+    "vitest": "^5.0.5",
+    "@forthtilliath/eslint-config": "0.10.0",
+    "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {
     "dev": "tsc --watch -p tsconfig.build.json",