@ekim088/toolkit 0.3.0 → 0.4.0

package/README.md

@@ -4,12 +4,37 @@ A simple JavaScript utility library. See [documentation](docs).
 
 ## Installation
 
+Install via npm or yarn:
+
 ```
 yarn add @ekim088/toolkit
 ```
 
 ## Usage
 
+This package supports for barrel and subpath imports:
+
 ```
 import { clone } from '@ekim088/toolkit';
 ```
+
+or
+
+```
+import { clone } from '@ekim088/toolkit/clone';
+```
+
+## Releasing
+
+Releases are automated using [changesets](https://github.com/changesets/changesets):
+
+1. In your feature PR, run `yarn changeset` to pick the bump type
+   (major/minor/patch) and add a description of your changes. Commit the
+   generated markdown file in `.changeset/` with your changes. **Only changes
+   that impact the published package require a changeset.**
+2. When the PR merges to `main`, the Release workflow opens (or updates) a
+   "Version Packages" PR that aggregates all pending changesets: it bumps the
+   version, updates `CHANGELOG.md`, and regenerates the typedoc output in
+   `docs/`.
+3. Merge the "Version Packages" PR to publish to npm. A Discord notification
+   confirms the publish.

package/lib/@types/chunk.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Chunks an array into sub-arrays of at most `chunkSize` items.
+ * @template T
+ * @param {T[]} array The array to chunk.
+ * @param {number} chunkSize The max number of items per chunk.
+ * @returns {T[][]} The chunked array.
+ */
+export declare function chunk<T>(array: readonly T[], chunkSize: number): T[][];

package/lib/@types/clone.d.ts

@@ -3,4 +3,4 @@
  * @param {*} value The value to clone.
  * @returns {*} A copy of the value.
  */
-export default function clone<T = unknown>(value: T): T;
+export declare function clone<T = unknown>(value: T): T;

package/lib/@types/createObjectFactory.d.ts

@@ -0,0 +1,17 @@
+import { type RecursivePartial } from './typeUtils.js';
+export type ObjectFactoryConfig = {
+    /**
+     * If `true`, deeply merges overrides into the default object.
+     */
+    mergeDeep?: boolean;
+};
+export type ObjectFactoryFn<T extends object> = (overrides?: RecursivePartial<T>, config?: ObjectFactoryConfig) => T;
+/**
+ * Creates a factory function that returns an object of a given type.
+ * @param {object} defaultObj The default object to return when calling the
+ * 	factory function.
+ * @returns {Function} A factory function that returns a new object of a given
+ * 	type. Accepts an object argument that shallowly overrides properties on the
+ * 	default object.
+ */
+export declare function createObjectFactory<T extends object>(defaultObj: T): ObjectFactoryFn<T>;

package/lib/@types/index.d.ts

@@ -1,9 +1,17 @@
-export { default as clone } from './clone';
-export { default as isBoolean } from './isBoolean';
-export { default as isDeepEqual } from './isDeepEqual';
-export { default as isNumber } from './isNumber';
-export { default as isObject } from './isObject';
-export { default as isString } from './isString';
-export { default as memoizeOne, type MemoizedFn, type EqualityFn, } from './memoizeOne';
-export { default as merge, type Merged } from './merge';
-export * from './typeUtils';
+export * from './chunk.js';
+export * from './clone.js';
+export * from './createObjectFactory.js';
+export * from './isBoolean.js';
+export * from './isDeepEqual.js';
+export * from './isNullish.js';
+export * from './isNumber.js';
+export * from './isObject.js';
+export * from './isString.js';
+export * from './isUndefined.js';
+export * from './memoizeOne.js';
+export * from './merge.js';
+export * from './pick.js';
+export * from './shuffle.js';
+export * from './truthy.js';
+export * from './typeUtils.js';
+export * from './uuid.js';

package/lib/@types/isBoolean.d.ts

@@ -3,4 +3,4 @@
  * @param {*} value The value to test.
  * @returns {boolean} `true` if the value is a boolean.
  */
-export default function isBoolean(value: unknown): value is boolean;
+export declare function isBoolean(value: unknown): value is boolean;

package/lib/@types/isDeepEqual.d.ts

@@ -5,4 +5,4 @@
  * @param {*} b An argument to test.
  * @returns {boolean} `true` if `a` and `b` are deeply equal.
  */
-export default function isDeepEqual(a: unknown, b: unknown): boolean;
+export declare function isDeepEqual(a: unknown, b: unknown): boolean;

package/lib/@types/isNullish.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tests if a value is `null` or `undefined`.
+ * @param {*} value The value to test.
+ * @returns {boolean} `true` if the value is `null` or `undefined`.
+ */
+export declare function isNullish(value: unknown): value is null | undefined;

package/lib/@types/isNumber.d.ts

@@ -3,4 +3,4 @@
  * @param {*} value The value to test.
  * @returns {boolean} `true` if the value is a number.
  */
-export default function isNumber(value: unknown): value is number;
+export declare function isNumber(value: unknown): value is number;

package/lib/@types/isObject.d.ts

@@ -4,4 +4,4 @@
  * @returns {boolean} `true` if the value is an object. Returns `false` for
  *  arrays and `null`.
  */
-export default function isObject(value: unknown): value is object;
+export declare function isObject(value: unknown): value is object;

package/lib/@types/isString.d.ts

@@ -3,4 +3,4 @@
  * @param {*} value The value to test.
  * @returns {boolean} `true` if the value is a string.
  */
-export default function isString(value: unknown): value is string;
+export declare function isString(value: unknown): value is string;

package/lib/@types/isUndefined.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tests if a value is `undefined`.
+ * @param {*} value The value to test.
+ * @returns {boolean} `true` if the value is `undefined`.
+ */
+export declare function isUndefined(value: unknown): value is undefined;

package/lib/@types/memoizeOne.d.ts

@@ -15,4 +15,4 @@ export type EqualityFn<T extends (...args: any) => unknown> = (newArgs: Paramete
  *  if the equality function returns `true`.
  * @returns {Function} The memoized function.
  */
-export default function memoizeOne<T extends (...args: any) => unknown>(fn: T, equalityFn?: EqualityFn<T>): MemoizedFn<T>;
+export declare function memoizeOne<T extends (...args: any) => unknown>(fn: T, equalityFn?: EqualityFn<T>): MemoizedFn<T>;

package/lib/@types/merge.d.ts

@@ -8,4 +8,4 @@ export type Merged<T extends object[]> = T extends [
  * @param {object[]} objects Any number of object literals to merge.
  * @returns {object} A new object with the properties of its source objects.
  */
-export default function merge<T extends object[]>(...objects: T): Merged<T>;
+export declare function merge<T extends object[]>(...objects: T): Merged<T>;

package/lib/@types/pick.d.ts

@@ -0,0 +1,10 @@
+import { type ValueOf } from './typeUtils.js';
+/**
+ * Returns an object with only the properties that pass a given test.
+ * @param {object} obj The object to parse.
+ * @param {Function} predicate A test function called against each object
+ * 	property. Properties that return a falsy result will not be included.
+ * @returns {object} A new object containing only the properties that passed the
+ * 	test.
+ */
+export declare function pick<T extends object>(obj: T, predicate: (val: ValueOf<T>, key: keyof T) => boolean): Partial<T>;

package/lib/@types/shuffle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shuffles the items in an array.
+ * @template T
+ * @param {T[]} array The array to shuffle.
+ * @returns {T[]} The chunked array.
+ */
+export declare function shuffle<T = unknown>(array: T[]): T[];

package/lib/@types/truthy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tests if a value is truthy. Can be passed as the callback to an Array
+ * `filter()` method to correctly infer the type of the resulting array items.
+ * ```
+ * const arr: (string | undefined)[] = [];
+ * const truthyArr1: string[] = arr.filter(Boolean); // TS error
+ * const truthyArr2: string[] = arr.filter(truthy); // no TS error
+ * ```
+ * @param {*} value The value to test.
+ * @returns {boolean} `true` if the value is truthy.
+ */
+export declare function truthy<TruthyValue>(value: TruthyValue | null | undefined | '' | 0 | false): value is TruthyValue;

package/lib/@types/typeUtils.d.ts

@@ -1,13 +1,13 @@
-/**
- * Derives the item type from an array.
- */
-export type ItemType<T> = T extends (infer U)[] ? U : never;
 /**
  * Declares an object and its nested objects as partials.
  */
 export type RecursivePartial<T> = {
     [P in keyof T]?: T[P] extends Record<keyof any, unknown> ? RecursivePartial<T[P]> : T[P];
 };
+/**
+ * Derives the item type from an array or object.
+ */
+export type ValueOf<T> = T extends (infer U)[] ? U : T extends object ? T[keyof T] : never;
 /**
  * Makes a readonly object mutable.
  */

package/lib/@types/uuid.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a random UUID.
+ * @returns {string} A UUID.
+ */
+export declare function uuid(): string;

package/lib/chunk.js

@@ -0,0 +1,17 @@
+/**
+ * Chunks an array into sub-arrays of at most `chunkSize` items.
+ * @template T
+ * @param {T[]} array The array to chunk.
+ * @param {number} chunkSize The max number of items per chunk.
+ * @returns {T[][]} The chunked array.
+ */
+export function chunk(array, chunkSize) {
+    const result = [];
+    if (chunkSize < 1) {
+        return [];
+    }
+    for (let i = 0; i < array.length; i += chunkSize) {
+        result.push([...array.slice(i, i + chunkSize)]);
+    }
+    return result;
+}

package/lib/clone.js

@@ -1,4 +1,4 @@
-import isObject from './isObject';
+import { isObject } from './isObject.js';
 function cloneObject(obj) {
     const clonedObj = {};
     for (const key in obj) {
@@ -13,7 +13,7 @@ function cloneObject(obj) {
  * @param {*} value The value to clone.
  * @returns {*} A copy of the value.
  */
-export default function clone(value) {
+export function clone(value) {
     if (Array.isArray(value)) {
         return value.map(item => clone(item));
     }

package/lib/createObjectFactory.js

@@ -0,0 +1,22 @@
+import { clone } from './clone.js';
+import { merge } from './merge.js';
+/**
+ * Creates a factory function that returns an object of a given type.
+ * @param {object} defaultObj The default object to return when calling the
+ * 	factory function.
+ * @returns {Function} A factory function that returns a new object of a given
+ * 	type. Accepts an object argument that shallowly overrides properties on the
+ * 	default object.
+ */
+export function createObjectFactory(defaultObj) {
+    const defaultCopy = clone(defaultObj);
+    return (overrides, { mergeDeep } = {}) => {
+        const newObject = clone(defaultCopy);
+        if (overrides) {
+            return mergeDeep
+                ? merge(newObject, overrides)
+                : { ...newObject, ...overrides };
+        }
+        return newObject;
+    };
+}

package/lib/index.js

@@ -1,9 +1,17 @@
-export { default as clone } from './clone';
-export { default as isBoolean } from './isBoolean';
-export { default as isDeepEqual } from './isDeepEqual';
-export { default as isNumber } from './isNumber';
-export { default as isObject } from './isObject';
-export { default as isString } from './isString';
-export { default as memoizeOne, } from './memoizeOne';
-export { default as merge } from './merge';
-export * from './typeUtils';
+export * from './chunk.js';
+export * from './clone.js';
+export * from './createObjectFactory.js';
+export * from './isBoolean.js';
+export * from './isDeepEqual.js';
+export * from './isNullish.js';
+export * from './isNumber.js';
+export * from './isObject.js';
+export * from './isString.js';
+export * from './isUndefined.js';
+export * from './memoizeOne.js';
+export * from './merge.js';
+export * from './pick.js';
+export * from './shuffle.js';
+export * from './truthy.js';
+export * from './typeUtils.js';
+export * from './uuid.js';

package/lib/isBoolean.js

@@ -3,6 +3,6 @@
  * @param {*} value The value to test.
  * @returns {boolean} `true` if the value is a boolean.
  */
-export default function isBoolean(value) {
+export function isBoolean(value) {
     return typeof value === 'boolean';
 }

package/lib/isDeepEqual.js

@@ -1,4 +1,4 @@
-import isObject from './isObject';
+import { isObject } from './isObject.js';
 /**
  * Tests if two arguments are equal. Object literals and arrays are tested for
  * deep equality while other objects are tested for strict equality.
@@ -6,7 +6,7 @@ import isObject from './isObject';
  * @param {*} b An argument to test.
  * @returns {boolean} `true` if `a` and `b` are deeply equal.
  */
-export default function isDeepEqual(a, b) {
+export function isDeepEqual(a, b) {
     if (typeof a !== typeof b) {
         return false;
     }

package/lib/isNullish.js

@@ -0,0 +1,8 @@
+/**
+ * Tests if a value is `null` or `undefined`.
+ * @param {*} value The value to test.
+ * @returns {boolean} `true` if the value is `null` or `undefined`.
+ */
+export function isNullish(value) {
+    return value == null;
+}

package/lib/isNumber.js

@@ -3,6 +3,6 @@
  * @param {*} value The value to test.
  * @returns {boolean} `true` if the value is a number.
  */
-export default function isNumber(value) {
+export function isNumber(value) {
     return typeof value === 'number';
 }

package/lib/isObject.js

@@ -4,6 +4,6 @@
  * @returns {boolean} `true` if the value is an object. Returns `false` for
  *  arrays and `null`.
  */
-export default function isObject(value) {
+export function isObject(value) {
     return !!value && value.constructor === Object;
 }

package/lib/isString.js

@@ -3,6 +3,6 @@
  * @param {*} value The value to test.
  * @returns {boolean} `true` if the value is a string.
  */
-export default function isString(value) {
+export function isString(value) {
     return typeof value === 'string';
 }

package/lib/isUndefined.js

@@ -0,0 +1,8 @@
+/**
+ * Tests if a value is `undefined`.
+ * @param {*} value The value to test.
+ * @returns {boolean} `true` if the value is `undefined`.
+ */
+export function isUndefined(value) {
+    return typeof value === 'undefined';
+}

package/lib/memoizeOne.js

@@ -1,4 +1,4 @@
-import isDeepEqual from './isDeepEqual';
+import { isDeepEqual } from './isDeepEqual.js';
 /**
  * Returns a memoized function that caches the last result of a function call.
  * The cached result is returned if the function arguments remain the same. Only
@@ -9,7 +9,7 @@ import isDeepEqual from './isDeepEqual';
  *  if the equality function returns `true`.
  * @returns {Function} The memoized function.
  */
-export default function memoizeOne(fn, equalityFn) {
+export function memoizeOne(fn, equalityFn) {
     let cache = null;
     function memoizedFn(...args) {
         if (cache &&

package/lib/merge.js

@@ -1,11 +1,11 @@
-import isObject from './isObject';
+import { isObject } from './isObject.js';
 /**
  * Deeply merges a list of objects into a single object. For duplicate
  * properties, subsequent occurrences overwrite the previous.
  * @param {object[]} objects Any number of object literals to merge.
  * @returns {object} A new object with the properties of its source objects.
  */
-export default function merge(...objects) {
+export function merge(...objects) {
     const mergedObj = {};
     objects.forEach(obj => {
         Object.keys(obj).forEach(key => {

package/lib/pick.js

@@ -0,0 +1,13 @@
+/**
+ * Returns an object with only the properties that pass a given test.
+ * @param {object} obj The object to parse.
+ * @param {Function} predicate A test function called against each object
+ * 	property. Properties that return a falsy result will not be included.
+ * @returns {object} A new object containing only the properties that passed the
+ * 	test.
+ */
+export function pick(obj, predicate) {
+    return Object.entries(obj).reduce((picked, [key, value]) => predicate(value, key)
+        ? { ...picked, [key]: value }
+        : picked, {});
+}

package/lib/shuffle.js

@@ -0,0 +1,15 @@
+/**
+ * Shuffles the items in an array.
+ * @template T
+ * @param {T[]} array The array to shuffle.
+ * @returns {T[]} The chunked array.
+ */
+export function shuffle(array) {
+    const shuffled = array.slice();
+    for (let i = shuffled.length - 1; i > 0; i--) {
+        // pick a random number from 0 to i and swap the elements at the two indices
+        const j = Math.floor(Math.random() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+}

package/lib/truthy.js

@@ -0,0 +1,14 @@
+/**
+ * Tests if a value is truthy. Can be passed as the callback to an Array
+ * `filter()` method to correctly infer the type of the resulting array items.
+ * ```
+ * const arr: (string | undefined)[] = [];
+ * const truthyArr1: string[] = arr.filter(Boolean); // TS error
+ * const truthyArr2: string[] = arr.filter(truthy); // no TS error
+ * ```
+ * @param {*} value The value to test.
+ * @returns {boolean} `true` if the value is truthy.
+ */
+export function truthy(value) {
+    return !!value;
+}

package/lib/uuid.js

@@ -0,0 +1,7 @@
+/**
+ * Generates a random UUID.
+ * @returns {string} A UUID.
+ */
+export function uuid() {
+    return crypto.randomUUID();
+}

package/package.json

@@ -1,55 +1,82 @@
 {
-  "name": "@ekim088/toolkit",
-  "description": "A simple JavaScript utility library.",
-  "version": "0.3.0",
-  "author": "ekim088 <edward@cyberbird.co>",
-  "type": "module",
-  "license": "MIT",
-  "main": "./lib/index.js",
-  "types": "./lib/@types/index.d.ts",
-  "scripts": {
-    "build": "rm -rf ./lib && tsc & yarn docs",
-    "docs": "typedoc",
-    "format": "yarn exec prettier . --write",
-    "lint": "yarn lint:js && yarn lint:types",
-    "lint:js": "eslint . --fix",
-    "lint:types": "tsc --noEmit",
-    "test": "vitest",
-    "test:ci": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:pre-commit": "vitest related --run",
-    "_postinstall": "husky",
-    "prepack": "pinst --disable",
-    "postpack": "pinst --enable"
-  },
-  "devDependencies": {
-    "@commitlint/cli": "^19.8.1",
-    "@commitlint/config-conventional": "^19.8.1",
-    "@eslint/js": "^9.27.0",
-    "@types/node": "^22.15.29",
-    "@vitest/coverage-v8": "3.1.4",
-    "@vitest/eslint-plugin": "^1.2.1",
-    "eslint": "^9.27.0",
-    "eslint-plugin-jsdoc": "^50.6.17",
-    "global-jsdom": "^26.0.0",
-    "globals": "^16.2.0",
-    "husky": "^9.1.7",
-    "jsdom": "^26.1.0",
-    "lint-staged": "^16.0.0",
-    "pinst": "^3.0.0",
-    "prettier": "3.5.3",
-    "typedoc": "^0.28.5",
-    "typedoc-plugin-markdown": "^4.6.3",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.32.1",
-    "vitest": "^3.1.4"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ekim088/toolkit.git"
-  },
-  "volta": {
-    "node": "22.16.0",
-    "yarn": "4.9.1"
-  }
-}
+	"name": "@ekim088/toolkit",
+	"description": "A simple JavaScript utility library.",
+	"version": "0.4.0",
+	"author": "ekim088 <edward@cyberbird.co>",
+	"type": "module",
+	"license": "MIT",
+	"main": "./lib/index.js",
+	"types": "./lib/@types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./lib/@types/index.d.ts",
+			"import": "./lib/index.js"
+		},
+		"./*": {
+			"types": "./lib/@types/*.d.ts",
+			"import": "./lib/*.js"
+		}
+	},
+	"files": [
+		"lib"
+	],
+	"sideEffects": false,
+	"engines": {
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "rm -rf ./lib && tsc",
+		"docs": "typedoc",
+		"format": "yarn exec prettier . --write",
+		"lint": "yarn lint:js && yarn lint:types",
+		"lint:js": "eslint . --fix",
+		"lint:package": "yarn build && yarn pack --out package.tgz && publint run package.tgz --strict && attw package.tgz --profile esm-only",
+		"lint:types": "tsc --noEmit",
+		"test": "vitest",
+		"test:ci": "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"test:pre-commit": "vitest related --run",
+		"_postinstall": "husky",
+		"prepack": "yarn pinst --disable",
+		"postpack": "yarn pinst --enable",
+		"release": "yarn build && yarn changeset publish",
+		"changeset:version": "yarn changeset version && yarn docs"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.3",
+		"@changesets/cli": "^2.31.0",
+		"@commitlint/cli": "^19.8.1",
+		"@commitlint/config-conventional": "^19.8.1",
+		"@eslint/js": "^9.27.0",
+		"@types/node": "^24.0.0",
+		"@vitest/coverage-v8": "3.1.4",
+		"@vitest/eslint-plugin": "^1.2.1",
+		"eslint": "^9.27.0",
+		"eslint-plugin-jsdoc": "^50.6.17",
+		"global-jsdom": "^26.0.0",
+		"globals": "^16.2.0",
+		"husky": "^9.1.7",
+		"jsdom": "^26.1.0",
+		"lint-staged": "^16.0.0",
+		"pinst": "^3.0.0",
+		"prettier": "3.5.3",
+		"publint": "^0.3.21",
+		"typedoc": "^0.28.5",
+		"typedoc-plugin-markdown": "^4.6.3",
+		"typescript": "^5.8.3",
+		"typescript-eslint": "^8.32.1",
+		"vitest": "^3.1.4"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ekim088/toolkit.git"
+	},
+	"packageManager": "yarn@4.9.1",
+	"volta": {
+		"node": "24.16.0",
+		"yarn": "4.9.1"
+	}
+}