@animaj/ts-utils 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,16 @@
+ISC License
+
+Copyright (c) 2020-2026 Julien Khong
+Copyright (c) 2026 Animaj
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,284 @@
-# Temporary Holding Version
+# @animaj/ts-utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Provides syntactic sugar and shortcuts to bullet-proof your TypeScript/JavaScript code.
+
+## Contents
+
+- [Install](#install)
+- [DevUtils](#devutils) — `isSet` · `isNotSet` · `isAllSet` · `isOneNotSet` · `isEmpty` · `getFieldValue` · `getChildFieldValue` · `makeSingleton` · `debounce` · `getError`
+- [StringUtils](#stringutils) — `isBlank` · `capitalize` · `uncapitalize` · `replaceTrailing` · `replaceLeading`
+- [ArrayUtils](#arrayutils) — `isEmpty` · `getField`
+- [DateUtils](#dateutils) — `addDays` · `addMinutes` · `addSeconds`
+- [FunctionUtils](#functionutils) — `isAsync`
+- [InMemory](#inmemory-cache) — TTL-based in-memory cache
+- [TestUtils](#testutils) — async test helpers
+
+---
+
+## Install
+
+```sh
+npm install @animaj/ts-utils
+```
+
+---
+
+## DevUtils
+
+### `isSet(value)`
+Returns `true` if the value is not `null`, not `undefined`, and not the string `'undefined'`.
+
+```ts
+import { DevUtils } from '@animaj/ts-utils';
+
+DevUtils.isSet(null);        // false
+DevUtils.isSet(undefined);   // false
+DevUtils.isSet('undefined'); // false
+DevUtils.isSet(0);           // true
+DevUtils.isSet('');          // true
+DevUtils.isSet(false);       // true
+```
+
+### `isNotSet(value)`
+Inverse of `isSet`.
+
+### `isAllSet(memberNames, data)` / `isOneNotSet(memberNames, data)`
+Check if all (or at least one) named fields of an object are set.
+
+```ts
+DevUtils.isAllSet(['id', 'name'], { id: 1, name: 'foo' }); // true
+DevUtils.isOneNotSet(['id', 'name'], { id: 1 });            // true
+```
+
+### `isEmpty(value)`
+Returns `true` for `null`, `undefined`, empty/blank strings, empty arrays, and empty objects.
+
+```ts
+DevUtils.isEmpty(null);      // true
+DevUtils.isEmpty('   ');     // true
+DevUtils.isEmpty([]);        // true
+DevUtils.isEmpty({});        // true
+DevUtils.isEmpty([1]);       // false
+DevUtils.isEmpty({ a: 1 }); // false
+```
+
+### `getFieldValue(struct, fieldname, default)`
+Returns the field value if set, otherwise the default.
+
+```ts
+DevUtils.getFieldValue({ age: 30 }, 'age', 0);  // 30
+DevUtils.getFieldValue({}, 'age', 0);            // 0
+DevUtils.getFieldValue(null, 'age', 0);          // 0
+```
+
+### `getChildFieldValue(struct, fieldnames, default)`
+Traverses nested objects safely, returning the default if any level is missing.
+
+```ts
+const obj = { a: { b: { c: 'deep' } } };
+DevUtils.getChildFieldValue(obj, ['a', 'b', 'c'], 'default'); // 'deep'
+DevUtils.getChildFieldValue(obj, ['a', 'x', 'c'], 'default'); // 'default'
+```
+
+### `makeSingleton(asyncFactory)`
+Wraps an async factory so it is called only once. Subsequent calls return the cached instance.
+
+```ts
+const getDb = DevUtils.makeSingleton(() => connectToDatabase());
+await getDb(); // connects
+await getDb(); // returns cached connection
+```
+
+### `debounce(fn, waitMs)`
+Returns a debounced version of `fn` that fires only after `waitMs` ms of inactivity.
+
+```ts
+const save = DevUtils.debounce(() => api.save(), 300);
+save(); save(); save(); // only the last call fires after 300ms
+```
+
+### `getError(e)`
+Normalizes any thrown value to an `Error` instance. Useful in `catch (e: unknown)` blocks.
+
+```ts
+try { ... } catch (e: unknown) {
+   const err = DevUtils.getError(e); // always an Error
+}
+```
+
+---
+
+## StringUtils
+
+```ts
+import { StringUtils } from '@animaj/ts-utils';
+```
+
+| Method | Description |
+|---|---|
+| `isBlank(str)` | `true` if string is null, undefined, or contains only whitespace |
+| `capitalize(word)` | Uppercases the first character |
+| `uncapitalize(word)` | Lowercases the first character |
+| `replaceTrailing(value, char, replacement)` | Replaces trailing occurrences of `char` |
+| `replaceLeading(value, char, replacement)` | Replaces leading occurrences of `char` |
+
+```ts
+StringUtils.capitalize('hello');                   // 'Hello'
+StringUtils.uncapitalize('World');                 // 'world'
+StringUtils.replaceTrailing('foo///', '/', '');    // 'foo'
+StringUtils.replaceLeading('///foo', '/', '');     // 'foo'
+```
+
+---
+
+## ArrayUtils
+
+```ts
+import { ArrayUtils } from '@animaj/ts-utils';
+```
+
+| Method | Description |
+|---|---|
+| `isEmpty(array)` | `true` if array is null, undefined, or has no elements |
+| `getField(array, index, fieldname, default)` | Safely reads a field from an element at a given index |
+
+```ts
+ArrayUtils.isEmpty([]);                              // true
+ArrayUtils.getField([{ id: 1 }], 0, 'id', null);   // 1
+ArrayUtils.getField([], 0, 'id', null);             // null
+```
+
+---
+
+## DateUtils
+
+```ts
+import { DateUtils } from '@animaj/ts-utils';
+```
+
+| Method | Description |
+|---|---|
+| `addDays(date, n)` | Returns a new Date with `n` days added |
+| `addMinutes(date, n)` | Returns a new Date with `n` minutes added |
+| `addSeconds(date, n)` | Returns a new Date with `n` seconds added |
+
+Accepts negative values to subtract. The original date is never mutated.
+
+```ts
+DateUtils.addDays(new Date(), 7);     // one week from now
+DateUtils.addSeconds(new Date(), -30); // 30 seconds ago
+```
+
+---
+
+## FunctionUtils
+
+```ts
+import { FunctionUtils } from '@animaj/ts-utils';
+```
+
+| Method | Description |
+|---|---|
+| `isAsync(fn)` | `true` if the function is async |
+
+```ts
+FunctionUtils.isAsync(async () => {}); // true
+FunctionUtils.isAsync(() => {});       // false
+```
+
+---
+
+## InMemory (cache)
+
+A TTL-based in-memory cache with per-entry TTL support and automatic background cleanup.
+
+```ts
+import { InMemory } from '@animaj/ts-utils';
+```
+
+### Constructor options
+
+| Option | Default | Description |
+|---|---|---|
+| `ttlInSec` | 3600 (1h) | Default TTL for entries |
+| `autoTtlCleanIntervalInSec` | 3600 (1h) | How often expired entries are swept |
+| `autoWipeAllIntervalInSec` | disabled | How often the entire cache is cleared (opt-in) |
+
+### Methods
+
+#### `add({ id, d, ttlInSec? })`
+Adds or overwrites an entry. `ttlInSec` overrides the global default for this entry.
+
+```ts
+const cache = new InMemory<User>({ ttlInSec: 300 });
+await cache.add({ id: 'u1', d: user });
+await cache.add({ id: 'u2', d: user, ttlInSec: 60 }); // custom TTL
+```
+
+#### `fetch(id)`
+Returns the cached value or `undefined` if missing or expired.
+
+```ts
+const user = await cache.fetch('u1'); // User | undefined
+```
+
+#### `fetchMultiple(ids)`
+Splits a list of ids into cached hits and ids that still need to be fetched from the source.
+
+```ts
+const { cachedData, idsToRequest } = await cache.fetchMultiple(['u1', 'u2', 'u3']);
+// cachedData    → [{ id: 'u1', data: User }, ...]
+// idsToRequest  → ['u3']
+
+const fresh = await api.getUsers(idsToRequest);
+```
+
+#### `remove(id)`
+Removes a single entry immediately.
+
+```ts
+await cache.remove('u1');
+```
+
+#### `forceTtlClean()`
+Triggers an immediate sweep to remove all expired entries.
+
+#### `forceWipeAll()`
+Clears all entries regardless of TTL.
+
+#### `destroy()`
+Stops background intervals and clears the cache. Call this when the cache instance is no longer needed to prevent timer leaks.
+
+```ts
+await cache.destroy();
+```
+
+---
+
+## TestUtils
+
+Helpers for structuring async tests with setup / run / assert phases.
+
+```ts
+import { TestUtils } from '@animaj/ts-utils';
+```
+
+### `testExpectedSuccess({ setPreconditions, run, checkPostconditions })`
+For testing a happy path. Returns `{ success: true }` or `{ success: false, error }`.
+
+```ts
+const result = await TestUtils.testExpectedSuccess({
+   setPreconditions: async () => buildInput(),
+   run: async (input) => myService.process(input),
+   checkPostconditions: async (output) => {
+      expect(output.status).toBe('ok');
+   },
+});
+expect(result.success).toBe(true);
+```
+
+### `testExpectedError({ setPreconditions, run, checkError, checkPostconditions })`
+For testing flows that return an error value (no exception thrown).
+
+### `testExpectedException({ setPreconditions, run, checkError, checkPostconditions })`
+For testing flows that are expected to throw.

package/dist/array.d.ts

@@ -0,0 +1,4 @@
+export declare class ArrayUtils {
+    static isEmpty(array: any[]): boolean;
+    static getField(array: any[], indexValue: any, fieldname: string, defval: any): any;
+}

package/dist/array.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArrayUtils = void 0;
+const dev_1 = require("./dev");
+class ArrayUtils {
+    static isEmpty(array) {
+        return dev_1.DevUtils.isEmpty(array);
+    }
+    static getField(array, indexValue, fieldname, defval) {
+        if (!Array.isArray(array)) {
+            return defval;
+        }
+        if (dev_1.DevUtils.isSet(array) && dev_1.DevUtils.isSet(array[indexValue]) && dev_1.DevUtils.isSet(array[indexValue][fieldname])) {
+            return array[indexValue][fieldname];
+        }
+        return defval;
+    }
+}
+exports.ArrayUtils = ArrayUtils;

package/dist/cache-manager/cache-manager.d.ts

@@ -0,0 +1,19 @@
+export interface CacheManager<Data> {
+    fetch: (id: string) => Promise<Data | undefined>;
+    add: (o: {
+        id: string;
+        d: Data;
+        ttlInSec?: number;
+    }) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    fetchMultiple: (ids: string[]) => Promise<{
+        idsToRequest: string[];
+        cachedData: Array<{
+            id: string;
+            data: Data;
+        }>;
+    }>;
+    forceTtlClean: () => Promise<void>;
+    forceWipeAll: () => Promise<void>;
+    destroy: () => Promise<void>;
+}

package/dist/cache-manager/cache-manager.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cache-manager/in-memory.d.ts

@@ -0,0 +1,35 @@
+import { CacheManager } from './cache-manager';
+export declare class InMemory<Data> implements CacheManager<Data> {
+    private readonly cache;
+    private readonly ttlInSec;
+    private readonly autoTtlCleanIntervalInSec;
+    private autoTtlCleanIntervalHandle;
+    private readonly autoWipeAllIntervalInSec;
+    private autoWipeAllIntervalHandle;
+    constructor(options?: {
+        ttlInSec?: number;
+        autoTtlCleanIntervalInSec?: number;
+        autoWipeAllIntervalInSec?: number;
+    });
+    fetchMultiple(ids: string[]): Promise<{
+        idsToRequest: string[];
+        cachedData: Array<{
+            id: string;
+            data: Data;
+        }>;
+    }>;
+    fetch(id: string): Promise<Data | undefined>;
+    add(o: {
+        id: string;
+        d: Data;
+        ttlInSec?: number;
+    }): Promise<void>;
+    remove(id: string): Promise<void>;
+    forceTtlClean(): Promise<void>;
+    private setAutoTtlCleanIntervalHandle;
+    private ttlClean;
+    forceWipeAll(): Promise<void>;
+    private setWipeAllIntervalHandle;
+    private wipeAll;
+    destroy(): Promise<void>;
+}

package/dist/cache-manager/in-memory.js

@@ -0,0 +1,121 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemory = void 0;
+const dates_1 = require("../dates");
+const oneMinInSec = 60;
+const _60minInSec = 60 * oneMinInSec;
+const MAX_INTEGER_32 = Math.pow(2, 31) - 1;
+class InMemory {
+    constructor(options) {
+        var _a, _b;
+        this.cache = new Map();
+        this.ttlInSec = _60minInSec;
+        this.autoTtlCleanIntervalInSec = _60minInSec;
+        if (options !== undefined) {
+            this.ttlInSec = (_a = options.ttlInSec) !== null && _a !== void 0 ? _a : this.ttlInSec;
+            this.autoTtlCleanIntervalInSec = (_b = options.autoTtlCleanIntervalInSec) !== null && _b !== void 0 ? _b : this.autoTtlCleanIntervalInSec;
+            this.autoWipeAllIntervalInSec = options.autoWipeAllIntervalInSec;
+        }
+        this.setAutoTtlCleanIntervalHandle();
+        this.setWipeAllIntervalHandle();
+    }
+    fetchMultiple(ids) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const idsToRequest = [];
+            const cachedData = [];
+            yield Promise.all(ids.map((id) => __awaiter(this, void 0, void 0, function* () {
+                const data = yield this.fetch(id);
+                if (data !== undefined) {
+                    cachedData.push({ id, data });
+                }
+                else {
+                    idsToRequest.push(id);
+                }
+            })));
+            return {
+                idsToRequest,
+                cachedData,
+            };
+        });
+    }
+    fetch(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const data = this.cache.get(id);
+            if (data === undefined) {
+                return undefined;
+            }
+            const timeLimit = dates_1.DateUtils.addSeconds(new Date(), -data.ttlInSec);
+            const isValidData = data.timestamp > timeLimit.getTime();
+            if (isValidData) {
+                return data.data;
+            }
+            this.remove(id);
+            return undefined;
+        });
+    }
+    add(o) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const ttlInSec = (_a = o.ttlInSec) !== null && _a !== void 0 ? _a : this.ttlInSec;
+            this.cache.set(o.id, { data: o.d, timestamp: new Date().getTime(), ttlInSec });
+        });
+    }
+    remove(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.cache.delete(id);
+        });
+    }
+    forceTtlClean() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.ttlClean();
+            this.setAutoTtlCleanIntervalHandle();
+        });
+    }
+    setAutoTtlCleanIntervalHandle() {
+        clearInterval(this.autoTtlCleanIntervalHandle);
+        this.autoTtlCleanIntervalHandle = setInterval(() => this.ttlClean(), toSafeIntervalMs(this.autoTtlCleanIntervalInSec));
+    }
+    ttlClean() {
+        this.cache.forEach((data, id) => {
+            const timeLimit = dates_1.DateUtils.addSeconds(new Date(), -data.ttlInSec);
+            if (data.timestamp <= timeLimit.getTime()) {
+                this.cache.delete(id);
+            }
+        });
+    }
+    forceWipeAll() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.wipeAll();
+            this.setWipeAllIntervalHandle();
+        });
+    }
+    setWipeAllIntervalHandle() {
+        clearInterval(this.autoWipeAllIntervalHandle);
+        if (this.autoWipeAllIntervalInSec !== undefined) {
+            this.autoWipeAllIntervalHandle = setInterval(() => this.wipeAll(), toSafeIntervalMs(this.autoWipeAllIntervalInSec));
+        }
+    }
+    wipeAll() {
+        this.cache.clear();
+    }
+    destroy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            clearInterval(this.autoTtlCleanIntervalHandle);
+            clearInterval(this.autoWipeAllIntervalHandle);
+            this.cache.clear();
+        });
+    }
+}
+exports.InMemory = InMemory;
+function toSafeIntervalMs(sec) {
+    return Math.min(sec * 1000, MAX_INTEGER_32);
+}

package/dist/dates.d.ts

@@ -0,0 +1,5 @@
+export declare class DateUtils {
+    static addDays(d: Readonly<Date>, quantity: number): Date;
+    static addMinutes(d: Readonly<Date>, quantity: number): Date;
+    static addSeconds(d: Readonly<Date>, quantity: number): Date;
+}

package/dist/dates.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DateUtils = void 0;
+class DateUtils {
+    static addDays(d, quantity) {
+        const newDate = new Date(d);
+        newDate.setDate(newDate.getDate() + quantity);
+        return newDate;
+    }
+    static addMinutes(d, quantity) {
+        const newDate = new Date(d);
+        newDate.setMinutes(newDate.getMinutes() + quantity);
+        return newDate;
+    }
+    static addSeconds(d, quantity) {
+        const newDate = new Date(d);
+        newDate.setSeconds(newDate.getSeconds() + quantity);
+        return newDate;
+    }
+}
+exports.DateUtils = DateUtils;

package/dist/dev.d.ts

@@ -0,0 +1,20 @@
+export declare class DevUtils {
+    static isSet<T = any>(obj: T | null | undefined): obj is T;
+    static isNotSet<T = any>(obj: T | null | undefined): obj is null | undefined;
+    static isOneNotSet(memberNames: string[], data: any): boolean;
+    static isAllSet(memberNames: string[], data: any): boolean;
+    static getFieldValue<T>(struct: Record<string, any>, fieldname: string, defval: T): T;
+    private static isEmptyArray;
+    private static isEmptyString;
+    static getChildFieldValue<T>(struct: Record<string, any>, fieldnames: string[], defval: T): T;
+    static isEmpty(value: any): boolean;
+    static makeSingleton<T>(callback: () => Promise<T>): () => Promise<T>;
+    /**
+     *
+     * @param func the function to execute
+     * @param waitForInMs the debounce time in milliseconds
+     * @returns
+     */
+    static debounce<F extends (...args: any[]) => void>(func: F, waitForInMs: number): (...args: Parameters<F>) => void;
+    static getError(e: unknown): Error;
+}

package/dist/dev.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevUtils = void 0;
+class DevUtils {
+    static isSet(obj) {
+        const res = undefined !== obj && null !== obj;
+        if (typeof obj === 'string') {
+            return res && 'undefined' !== obj;
+        }
+        return res;
+    }
+    static isNotSet(obj) {
+        return !this.isSet(obj);
+    }
+    static isOneNotSet(memberNames, data) {
+        let ret = false;
+        for (const member of memberNames) {
+            if (this.isNotSet(data[member])) {
+                ret = true;
+                break;
+            }
+        }
+        return ret;
+    }
+    static isAllSet(memberNames, data) {
+        return !this.isOneNotSet(memberNames, data);
+    }
+    static getFieldValue(struct, fieldname, defval) {
+        if (this.isSet(struct) && this.isSet(struct[fieldname])) {
+            return struct[fieldname];
+        }
+        return defval;
+    }
+    static isEmptyArray(array) {
+        if (!Array.isArray(array)) {
+            return true;
+        }
+        return this.isNotSet(array) || array.length === 0;
+    }
+    static isEmptyString(str) {
+        if ('string' !== typeof str) {
+            return true;
+        }
+        return this.isNotSet(str) || str.trim().length === 0;
+    }
+    static getChildFieldValue(struct, fieldnames, defval) {
+        let val = defval;
+        for (const fieldname of fieldnames) {
+            val = this.getFieldValue(struct, fieldname, defval);
+            if (val === defval) {
+                return defval;
+            }
+            struct = struct[fieldname];
+        }
+        return val;
+    }
+    static isEmpty(value) {
+        if (this.isNotSet(value)) {
+            return true;
+        }
+        if (Array.isArray(value)) {
+            return this.isEmptyArray(value);
+        }
+        if ('string' === typeof value) {
+            return this.isEmptyString(value);
+        }
+        if ('object' === typeof value) {
+            return Object.keys(value).length === 0;
+        }
+        return false;
+    }
+    static makeSingleton(callback) {
+        let singleton;
+        return () => {
+            return new Promise((resolve, reject) => {
+                if (singleton !== undefined) {
+                    resolve(singleton);
+                    return;
+                }
+                callback()
+                    .then((sglton) => {
+                    singleton = sglton;
+                    resolve(singleton);
+                })
+                    .catch((err) => {
+                    reject(err);
+                });
+            });
+        };
+    }
+    /**
+     *
+     * @param func the function to execute
+     * @param waitForInMs the debounce time in milliseconds
+     * @returns
+     */
+    static debounce(func, waitForInMs) {
+        let timeout;
+        return (...args) => {
+            clearTimeout(timeout);
+            timeout = setTimeout(() => {
+                func(...args);
+            }, waitForInMs);
+        };
+    }
+    static getError(e) {
+        if (e instanceof Error) {
+            return e;
+        }
+        if (typeof e === 'string') {
+            return new Error(e);
+        }
+        let error = 'unknown error';
+        if (e !== undefined && e.message !== undefined) {
+            error = e.message;
+        }
+        if (e !== undefined && e.error !== undefined) {
+            error += ' > ' + e.error;
+        }
+        return new Error(error);
+    }
+}
+exports.DevUtils = DevUtils;

package/dist/function.d.ts

@@ -0,0 +1,3 @@
+export declare class FunctionUtils {
+    static isAsync(fn: any): boolean;
+}

package/dist/function.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionUtils = void 0;
+const dev_1 = require("./dev");
+class FunctionUtils {
+    static isAsync(fn) {
+        if (dev_1.DevUtils.isNotSet(fn)) {
+            return false;
+        }
+        return fn.toString().includes('__awaiter') || fn.constructor.name === 'AsyncFunction';
+    }
+}
+exports.FunctionUtils = FunctionUtils;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { DevUtils } from './dev';
+export { StringUtils } from './string';
+export { ArrayUtils } from './array';
+export { FunctionUtils } from './function';
+export { TestUtils } from './tests';
+export { DateUtils } from './dates';
+export { InMemory } from './cache-manager/in-memory';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemory = exports.DateUtils = exports.TestUtils = exports.FunctionUtils = exports.ArrayUtils = exports.StringUtils = exports.DevUtils = void 0;
+var dev_1 = require("./dev");
+Object.defineProperty(exports, "DevUtils", { enumerable: true, get: function () { return dev_1.DevUtils; } });
+var string_1 = require("./string");
+Object.defineProperty(exports, "StringUtils", { enumerable: true, get: function () { return string_1.StringUtils; } });
+var array_1 = require("./array");
+Object.defineProperty(exports, "ArrayUtils", { enumerable: true, get: function () { return array_1.ArrayUtils; } });
+var function_1 = require("./function");
+Object.defineProperty(exports, "FunctionUtils", { enumerable: true, get: function () { return function_1.FunctionUtils; } });
+var tests_1 = require("./tests");
+Object.defineProperty(exports, "TestUtils", { enumerable: true, get: function () { return tests_1.TestUtils; } });
+var dates_1 = require("./dates");
+Object.defineProperty(exports, "DateUtils", { enumerable: true, get: function () { return dates_1.DateUtils; } });
+var in_memory_1 = require("./cache-manager/in-memory");
+Object.defineProperty(exports, "InMemory", { enumerable: true, get: function () { return in_memory_1.InMemory; } });

package/dist/string.d.ts

@@ -0,0 +1,7 @@
+export declare class StringUtils {
+    static isBlank(str: string): boolean;
+    static replaceTrailing(value: string, charToTrim: string, replacement: string): string;
+    static replaceLeading(value: string, charToTrim: string, replacement: string): string;
+    static uncapitalize(word: string): string;
+    static capitalize(word: string): string;
+}

package/dist/string.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StringUtils = void 0;
+const dev_1 = require("./dev");
+class StringUtils {
+    static isBlank(str) {
+        if ('string' !== typeof str) {
+            return true;
+        }
+        return dev_1.DevUtils.isEmpty(str);
+    }
+    static replaceTrailing(value, charToTrim, replacement) {
+        if (dev_1.DevUtils.isNotSet(value) || '' === value) {
+            return '';
+        }
+        const regExp = new RegExp(charToTrim[0] + '+$');
+        return value.replace(regExp, replacement);
+    }
+    static replaceLeading(value, charToTrim, replacement) {
+        if (dev_1.DevUtils.isNotSet(value) || '' === value) {
+            return '';
+        }
+        const regExp = new RegExp('^' + charToTrim[0] + '+');
+        return value.replace(regExp, replacement);
+    }
+    static uncapitalize(word) {
+        if (dev_1.DevUtils.isNotSet(word) || '' === word) {
+            return '';
+        }
+        const lowercase = word[0].toLowerCase();
+        if (word.length > 1) {
+            return lowercase + word.slice(1);
+        }
+        return lowercase;
+    }
+    static capitalize(word) {
+        if (dev_1.DevUtils.isNotSet(word) || '' === word) {
+            return '';
+        }
+        const uppercase = word[0].toUpperCase();
+        if (word.length > 1) {
+            return uppercase + word.slice(1);
+        }
+        return uppercase;
+    }
+}
+exports.StringUtils = StringUtils;

package/dist/tests.d.ts

@@ -0,0 +1,26 @@
+type Result = {
+    success: true;
+} | {
+    success: false;
+    error: Error;
+};
+export declare class TestUtils {
+    static testExpectedSuccess<Input, Output>(o: {
+        setPreconditions: () => Promise<Input>;
+        run: (i: Input) => Promise<Output>;
+        checkPostconditions: (o: Output) => Promise<void>;
+    }): Promise<Result>;
+    static testExpectedError<Input, Output>(o: {
+        setPreconditions: () => Promise<Input>;
+        run: (i: Input) => Promise<Output>;
+        checkError: (o: Output) => Promise<void>;
+        checkPostconditions: (o: Output) => Promise<void>;
+    }): Promise<Result>;
+    static testExpectedException<Input, Output>(o: {
+        setPreconditions: () => Promise<Input>;
+        run: (i: Input) => Promise<Output>;
+        checkError: (e: unknown) => Promise<void>;
+        checkPostconditions: () => Promise<void>;
+    }): Promise<Result>;
+}
+export {};

package/dist/tests.js

@@ -0,0 +1,57 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestUtils = void 0;
+const dev_1 = require("./dev");
+class TestUtils {
+    static testExpectedSuccess(o) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const input = yield o.setPreconditions();
+                const output = yield o.run(input);
+                yield o.checkPostconditions(output);
+                return { success: true };
+            }
+            catch (e) {
+                return { success: false, error: dev_1.DevUtils.getError(e) };
+            }
+        });
+    }
+    static testExpectedError(o) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const input = yield o.setPreconditions();
+                const output = yield o.run(input);
+                yield o.checkError(output);
+                yield o.checkPostconditions(output);
+                return { success: true };
+            }
+            catch (e) {
+                return { success: false, error: dev_1.DevUtils.getError(e) };
+            }
+        });
+    }
+    static testExpectedException(o) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const input = yield o.setPreconditions();
+                yield o.run(input);
+                return { success: false, error: new Error('No exception thrown') };
+            }
+            catch (e) {
+                yield o.checkError(e);
+                yield o.checkPostconditions();
+                return { success: true };
+            }
+        });
+    }
+}
+exports.TestUtils = TestUtils;

package/package.json

@@ -1,6 +1,49 @@
 {
-  "name": "@animaj/ts-utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+   "name": "@animaj/ts-utils",
+   "version": "1.0.0",
+   "description": "Shared TypeScript helpers for Animaj services: null/empty guards, safe nested reads, async singletons, TTL in-memory cache, test helpers",
+   "main": "dist/index.js",
+   "types": "dist/index.d.ts",
+   "files": [
+      "dist/**/*"
+   ],
+   "scripts": {
+      "build": "make build",
+      "test": "make test",
+      "format": "make format",
+      "lint": "make lint",
+      "prepublishOnly": "npm run lint && npm test",
+      "preversion": "npm run lint",
+      "version": "npm run format && git add -A src"
+   },
+   "author": "Animaj",
+   "contributors": [
+      "Julien Khong (original author)",
+      "Stefano (current maintainer)"
+   ],
+   "license": "ISC",
+   "homepage": "https://github.com/animaj-lab/ts-utils#readme",
+   "repository": {
+      "type": "git",
+      "url": "git+https://github.com/animaj-lab/ts-utils.git"
+   },
+   "bugs": {
+      "url": "https://github.com/animaj-lab/ts-utils/issues"
+   },
+   "publishConfig": {
+      "access": "public"
+   },
+   "devDependencies": {
+      "@typescript-eslint/eslint-plugin": "^2.30.0",
+      "@typescript-eslint/parser": "^2.30.0",
+      "eslint": "^6.8.0",
+      "eslint-config-prettier": "^6.11.0",
+      "husky": "^4.2.3",
+      "minimist": ">=1.2.2",
+      "mocha": "^5.1.0",
+      "prettier": "^2.0.2",
+      "typescript": "^6.0.3",
+      "vitest": "4.1.8"
+   },
+   "keywords": []
+}