@anil-labs/collection-js 0.1.0

package/dist/src/operations/mutations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure-style mutation helpers — they always return a new array. Helpers that
+ * also need a removed-value tuple (`pop`, `shift`, `splice`) return both pieces.
+ */
+export declare function pushOf<T>(items: readonly T[], values: readonly T[]): T[];
+export declare function prependOf<T>(items: readonly T[], value: T): T[];
+export declare function concatOf<T, U>(items: readonly T[], other: readonly U[]): (T | U)[];
+export declare function popOf<T>(items: readonly T[], count?: number): {
+    remaining: T[];
+    removed: T[];
+};
+export declare function shiftOf<T>(items: readonly T[], count?: number): {
+    remaining: T[];
+    removed: T[];
+};
+export declare function spliceOf<T>(items: readonly T[], start: number, deleteCount?: number, replacements?: readonly T[]): {
+    remaining: T[];
+    removed: T[];
+};
+export declare function pullOf<T>(items: readonly T[], target: T): {
+    remaining: T[];
+    removed: T | undefined;
+};
+/**
+ * `forget(key)` — supports numeric indexes (delete element at index) and
+ * string keys (delete property from each object element).
+ */
+export declare function forgetOf<T>(items: readonly T[], keys: readonly (number | string)[]): T[];
+export declare function putOf<T extends object, K extends keyof T>(items: readonly T[], key: K, value: T[K]): T[];
+/** Recursive object merge (Laravel `mergeRecursive`). */
+export declare function mergeRecursiveOf<T>(items: readonly T[], ...others: readonly (readonly T[])[]): T[];
+/**
+ * Shallow merge mirroring Laravel: a collection wrapping a single plain object
+ * models an associative array, so merging two such collections overwrites
+ * matching string keys (`{a,b}` ⊕ `{b,c}` → `{a,b',c}`). Any other shape —
+ * including a genuine list of multiple objects — is treated positionally and
+ * the values are appended. This avoids silently collapsing `[{a},{b}]` into a
+ * single object.
+ */
+export declare function mergeOf<T, U>(items: readonly T[], other: readonly U[]): (T | U)[];

package/dist/src/operations/objectOps.d.ts

@@ -0,0 +1,10 @@
+export declare function pluckOf<T>(items: readonly T[], key: string, keyBy?: string): unknown[] | Record<string, unknown>;
+export declare function onlyOf<T extends object>(items: readonly T[], keys: readonly (keyof T | string)[]): Partial<T>[];
+export declare function exceptOf<T extends object>(items: readonly T[], keys: readonly (keyof T | string)[]): Partial<T>[];
+export declare function selectOf<T extends object, K extends keyof T>(items: readonly T[], keys: K | readonly K[]): Pick<T, K>[];
+export declare function flipOf(items: readonly unknown[]): Record<string, number>;
+export declare function keysOf<T>(items: readonly T[]): string[];
+export declare function dotOf(items: readonly unknown[]): Record<string, unknown>;
+export declare function undotOf(items: readonly unknown[]): Record<string, unknown>;
+export declare function replaceShallow<T>(items: readonly T[], replacements: Record<number, T>): T[];
+export declare function replaceRecursiveOf<T>(items: readonly T[], patches: readonly unknown[]): T[];

package/dist/src/operations/random.d.ts

@@ -0,0 +1,2 @@
+export declare function randomOne<T>(items: readonly T[], random?: () => number): T | undefined;
+export declare function randomMany<T>(items: readonly T[], count: number, random?: () => number): T[];

package/dist/src/operations/reducers.d.ts

@@ -0,0 +1,9 @@
+export declare function reduceOf<T, R>(items: readonly T[], fn: (carry: R, item: T, index: number) => R, initial: R): R;
+/**
+ * Spread reduce — the reducer is called with the carry tuple spread, followed
+ * by the current item and its index, and returns the next carry tuple. Mirrors
+ * Laravel's `reduceSpread`:
+ *
+ *   reduceSpread((a, b, item) => [a + item, b * item], 0, 1)
+ */
+export declare function reduceSpreadOf<T, R extends readonly unknown[]>(items: readonly T[], fn: (...args: readonly unknown[]) => R, ...initials: R): R;

package/dist/src/operations/sequence.d.ts

@@ -0,0 +1,4 @@
+export declare function rangeOf(start: number, end: number, step?: number): number[];
+export declare function timesOf<T>(count: number, factory: (n: number) => T): T[];
+export declare function multiplyOf<T>(items: readonly T[], factor: number): T[];
+export declare function padOf<T>(items: readonly T[], size: number, value: T): T[];

package/dist/src/operations/setOps.d.ts

@@ -0,0 +1,14 @@
+export declare function diffOf<T>(items: readonly T[], other: readonly T[]): T[];
+export declare function diffAssocOf<T>(items: readonly T[], other: readonly Partial<T>[]): T[];
+export declare function diffAssocUsingOf<T>(items: readonly T[], other: readonly T[], comparator: (a: T, b: T) => number): T[];
+export declare function diffKeysOf<T extends object>(items: readonly T[], otherKeys: readonly (keyof T | string)[]): T[];
+export declare function intersectOf<T>(items: readonly T[], other: readonly T[]): T[];
+export declare function intersectUsingOf<T>(items: readonly T[], other: readonly T[], comparator: (a: T, b: T) => number): T[];
+export declare function intersectAssocOf<T extends object>(items: readonly T[], other: readonly Partial<T>[]): T[];
+export declare function intersectAssocUsingOf<T extends object>(items: readonly T[], other: Record<string, unknown>, comparator: (a: string, b: string) => number): T[];
+export declare function intersectByKeysOf<T extends object>(items: readonly T[], otherKeys: readonly (keyof T | string)[]): T[];
+export declare function unionOf<T>(items: readonly T[], other: readonly T[]): T[];
+/** Object-keyed union — original collection's keys take precedence. */
+export declare function unionObjectsOf<T extends object>(items: readonly T[], other: readonly T[]): T[];
+export declare function crossJoinOf<T>(...arrays: readonly (readonly T[])[]): T[][];
+export declare function duplicatesOf<T>(items: readonly T[], by?: (item: T) => unknown, strict?: boolean): Map<number, T>;

package/dist/src/operations/sliceOps.d.ts

@@ -0,0 +1,8 @@
+import { Predicate } from '../../support/types';
+export declare function takeOf<T>(items: readonly T[], count: number): T[];
+export declare function takeUntilOf<T>(items: readonly T[], target: T | Predicate<T>): T[];
+export declare function takeWhileOf<T>(items: readonly T[], predicate: Predicate<T>): T[];
+export declare function skipOf<T>(items: readonly T[], count: number): T[];
+export declare function skipUntilOf<T>(items: readonly T[], target: T | Predicate<T>): T[];
+export declare function skipWhileOf<T>(items: readonly T[], predicate: Predicate<T>): T[];
+export declare function sliceOf<T>(items: readonly T[], start: number, length?: number): T[];

package/dist/src/operations/sorting.d.ts

@@ -0,0 +1,11 @@
+import { RetrieverInput } from '../../support/valueRetriever';
+import { Comparator, SortDirection } from '../../support/types';
+export declare function sortOf<T>(items: readonly T[], comparator?: Comparator<T>): T[];
+export declare function sortDescOf<T>(items: readonly T[]): T[];
+export type SortBySpec<T> = RetrieverInput<T, unknown> | readonly [RetrieverInput<T, unknown>, SortDirection] | Comparator<T>;
+export declare function sortByOf<T>(items: readonly T[], spec: SortBySpec<T> | readonly SortBySpec<T>[], descending?: boolean): T[];
+export declare function sortByDescOf<T>(items: readonly T[], spec: SortBySpec<T>): T[];
+export declare function sortKeysOf<T extends object>(items: readonly T[], descending?: boolean): T[];
+export declare function sortKeysUsingOf<T extends object>(items: readonly T[], comparator: (a: string, b: string) => number): T[];
+export declare function shuffleOf<T>(items: readonly T[], random?: () => number): T[];
+export declare function reverseOf<T>(items: readonly T[]): T[];

package/dist/src/operations/stats.d.ts

@@ -0,0 +1,30 @@
+import { RetrieverInput } from '../../support/valueRetriever';
+/** Population variance (divides by N). For sample variance, use `sampleVarianceOf`. */
+export declare function varianceOf<T>(items: readonly T[], by?: RetrieverInput<T, number>): number | undefined;
+/** Sample variance (divides by N-1). Returns `undefined` for fewer than 2 samples. */
+export declare function sampleVarianceOf<T>(items: readonly T[], by?: RetrieverInput<T, number>): number | undefined;
+export declare function stddevOf<T>(items: readonly T[], by?: RetrieverInput<T, number>): number | undefined;
+export declare function sampleStddevOf<T>(items: readonly T[], by?: RetrieverInput<T, number>): number | undefined;
+/**
+ * Quantile via linear interpolation between closest ranks (matches numpy/R type 7).
+ * `q` is in [0, 1]. Returns undefined for empty input.
+ */
+export declare function quantileOf<T>(items: readonly T[], q: number, by?: RetrieverInput<T, number>): number | undefined;
+export declare function percentileOf<T>(items: readonly T[], p: number, by?: RetrieverInput<T, number>): number | undefined;
+export interface HistogramBin {
+    count: number;
+    /** Lower bound (inclusive). */
+    from: number;
+    /** Upper bound (exclusive, except for the last bin which is inclusive). */
+    to: number;
+}
+/**
+ * Equal-width histogram with `bins` buckets. `range` is auto-computed when
+ * not supplied. Empty input returns an empty array.
+ */
+export declare function histogramOf<T>(items: readonly T[], bins: number, options?: {
+    by?: RetrieverInput<T, number>;
+    range?: readonly [number, number];
+}): HistogramBin[];
+/** Pearson correlation between two numeric extractors over the same items. */
+export declare function correlationOf<T>(items: readonly T[], xBy: RetrieverInput<T, number>, yBy: RetrieverInput<T, number>): number | undefined;

package/dist/src/operations/strings.d.ts

@@ -0,0 +1,2 @@
+export declare function implodeOf<T>(items: readonly T[], glueOrFormatter: string | ((item: T, index: number) => string), separatorIfFormatter?: string, key?: string): string;
+export declare function joinOf<T>(items: readonly T[], glue: string, finalGlue?: string): string;

package/dist/src/operations/transformations.d.ts

@@ -0,0 +1,9 @@
+import { ClassConstructor } from '../../support/types';
+export declare function mapOf<T, R>(items: readonly T[], fn: (item: T, index: number) => R): R[];
+export declare function mapIntoOf<T, R>(items: readonly T[], Ctor: ClassConstructor<R, [T]>): R[];
+export declare function mapSpreadOf<R>(items: ReadonlyArray<readonly unknown[]>, fn: (...args: readonly unknown[]) => R): R[];
+export declare function mapToGroupsOf<T, K extends PropertyKey, V>(items: readonly T[], fn: (item: T, index: number) => readonly [K, V]): Record<K, V[]>;
+export declare function mapWithKeysOf<T, K extends PropertyKey, V>(items: readonly T[], fn: (item: T, index: number) => readonly [K, V]): Record<K, V>;
+export declare function flatMapOf<T, R>(items: readonly T[], fn: (item: T, index: number) => R | readonly R[]): R[];
+export declare function flattenOf(items: readonly unknown[], depth?: number): unknown[];
+export declare function collapseOf<T>(items: readonly (readonly T[] | T)[]): T[];

package/dist/src/operations/uniqueness.d.ts

@@ -0,0 +1,3 @@
+import { RetrieverInput } from '../../support/valueRetriever';
+export declare function uniqueOf<T>(items: readonly T[], by?: RetrieverInput<T>, strict?: boolean): T[];
+export declare function uniqueStrictOf<T>(items: readonly T[], by?: RetrieverInput<T>): T[];

package/dist/src/support/arrayWrap.d.ts

@@ -0,0 +1,6 @@
+/** Convert any iterable / Arrayable / single value into a plain array. */
+export declare function toArray<T>(value: Iterable<T> | ArrayLike<T> | T): T[];
+/** Wrap a non-array value into an array. Null/undefined become an empty array. */
+export declare function arrayWrap<T>(value: T | T[] | null | undefined): T[];
+/** Identity transform — preserves the input when already an array. */
+export declare function ensureArray<T>(value: Iterable<T> | T[]): T[];

package/dist/src/support/dataGet.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve a nested value from an object/array using "dot" notation, mirroring
+ * Laravel's `data_get` helper. Supports `*` to traverse arrays and produces
+ * arrays of leaf values when wildcards are used.
+ */
+export declare function dataGet(target: unknown, path: string | readonly string[], defaultValue?: unknown): unknown;
+/** Set a nested value via dot path; mutates and returns the target. */
+export declare function dataSet(target: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;

package/dist/src/support/deepClone.d.ts

@@ -0,0 +1 @@
+export declare function deepClone<T>(value: T): T;

package/dist/src/support/deepEqual.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Recursive structural equality for arrays, plain objects, primitives, Date, RegExp.
+ * Cycles are not handled — assume DAG-shaped data (typical for collection items).
+ */
+export declare function deepEqual<T>(a: T, b: T): boolean;
+/**
+ * Loose comparison emulating PHP's `==` for the common cases used in
+ * Laravel collections (strings vs numbers, etc.). Falls back to deep equality
+ * for object-like values.
+ */
+export declare function looseEqual(a: unknown, b: unknown): boolean;

package/dist/src/support/index.d.ts

@@ -0,0 +1,8 @@
+export * from '../../support/types';
+export * from '../../support/isObject';
+export * from '../../support/deepEqual';
+export * from '../../support/deepClone';
+export * from '../../support/dataGet';
+export * from '../../support/valueRetriever';
+export * from '../../support/operatorForWhere';
+export * from '../../support/arrayWrap';

package/dist/src/support/isObject.d.ts

@@ -0,0 +1,4 @@
+import { PlainObject } from '../../support/types';
+export declare function isPlainObject(value: unknown): value is PlainObject;
+export declare function isObjectLike(value: unknown): value is Record<string, unknown>;
+export declare function isFunction(value: unknown): value is (...args: readonly unknown[]) => unknown;

package/dist/src/support/operatorForWhere.d.ts

@@ -0,0 +1,4 @@
+import { Operator } from '../../support/types';
+/** Compare two values using a Laravel-style operator string. */
+export declare function operatorForWhere(retrieved: unknown, operator: Operator, value: unknown): boolean;
+export declare function isOperator(value: unknown): value is Operator;

package/dist/src/support/types.d.ts

@@ -0,0 +1,15 @@
+export type PlainObject = Record<string, unknown>;
+export type Scalar = string | number | bigint | boolean | symbol;
+export type Comparable = string | number | bigint | boolean | Date;
+export type Operator = '=' | '==' | '===' | '!=' | '!==' | '<>' | '<' | '<=' | '>' | '>=';
+export type SortDirection = 'asc' | 'desc';
+export type Predicate<T> = (item: T, key: number) => boolean;
+export type Iteratee<T, R = unknown> = ((item: T, key: number) => R) | keyof T | string;
+export type ValueOf<T, K> = K extends keyof T ? T[K] : unknown;
+export type Comparator<T> = (a: T, b: T) => number;
+export type FlattenDepth1<T> = T extends ReadonlyArray<infer U> ? U : T;
+export type FlattenDepth2<T> = T extends ReadonlyArray<infer U> ? FlattenDepth1<U> : T;
+export type FlattenDepth3<T> = T extends ReadonlyArray<infer U> ? FlattenDepth2<U> : T;
+/** Approximation; for unbounded depth use `unknown` at runtime. */
+export type DeepFlatten<T> = T extends ReadonlyArray<infer U> ? DeepFlatten<U> : T;
+export type ClassConstructor<T, A extends readonly unknown[] = readonly unknown[]> = new (...args: A) => T;

package/dist/src/support/valueRetriever.d.ts

@@ -0,0 +1,7 @@
+export type RetrieverInput<T, R = unknown> = ((item: T, index: number) => R) | keyof T | string;
+/**
+ * Convert a key, dot-path, or function into a normalized accessor. Used by
+ * groupBy, keyBy, sortBy, sum-with-key, etc. — any operation that accepts
+ * either a callback or a property reference.
+ */
+export declare function valueRetriever<T, R = unknown>(source: RetrieverInput<T, R> | undefined): (item: T, index: number) => R;

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@anil-labs/collection-js",
+  "version": "0.1.0",
+  "description": "A fluent, Laravel-inspired Collection library for JavaScript and TypeScript. Provides 120+ chainable methods for elegant array manipulation.",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.umd.cjs",
+  "module": "dist/index.es.js",
+  "types": "dist/src/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.umd.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anilkumarthakur60/collection-js.git"
+  },
+  "homepage": "https://github.com/anilkumarthakur60/collection-js#readme",
+  "bugs": {
+    "url": "https://github.com/anilkumarthakur60/collection-js/issues"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "peerDependencies": {
+    "@types/node": ">=16"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "prepublishOnly": "npm run build && npm test",
+    "preview": "vite preview",
+    "test": "jest",
+    "lint": "eslint . --fix",
+    "format": "prettier --write src/ docs/",
+    "lint-format": "npm run lint && npm run format",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "ctf": "clear && npm run format && npm run lint && npm run test"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@rushstack/eslint-patch": "^1.16.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
+    "@typescript-eslint/parser": "^8.57.1",
+    "eslint": "^10.1.0",
+    "eslint-plugin-perfectionist": "^5.7.0",
+    "jest": "^30.4.2",
+    "prettier": "^3.8.3",
+    "ts-jest": "^29.4.11",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.57.1",
+    "vite": "^8.0.14",
+    "vite-plugin-dts": "^4.5.4",
+    "vitepress": "^1.6.4"
+  },
+  "keywords": [
+    "collection",
+    "data-structure",
+    "typescript",
+    "javascript",
+    "library",
+    "laravel",
+    "laravel-collections",
+    "collection-js",
+    "collection-ts",
+    "array",
+    "fluent",
+    "chainable",
+    "functional",
+    "manipulation"
+  ]
+}