@rudderjs/support 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleiman Shahbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+# @rudderjs/support
+
+Shared utility primitives for RudderJS: collections, environment access, config lookup, debug helpers, and general-purpose functions.
+
+All exports are also available from `@rudderjs/core` — you rarely need to install this package directly.
+
+## Installation
+
+```bash
+pnpm add @rudderjs/support
+```
+
+---
+
+## `config()`
+
+Read values from the application's `ConfigRepository` using dot-notation keys. The store is populated from your `config/` files at bootstrap time.
+
+```ts
+import { config } from '@rudderjs/core'
+
+config('app.name')           // → 'RudderJS'
+config('app.debug')          // → false
+config('cache.ttl', 60)      // → number (with fallback)
+```
+
+Keys follow the `file.key` pattern — `app.name` reads `configs.app.name` from `config/index.ts`.
+
+### `ConfigRepository` class
+
+```ts
+import { ConfigRepository } from '@rudderjs/support'
+
+const repo = new ConfigRepository({ db: { host: 'localhost', port: 5432 } })
+
+repo.get('db.host')            // 'localhost'
+repo.get('db.port', 3306)      // 5432   (falsy-safe — 0, false, '' are returned as-is)
+repo.get('db.missing', 'n/a')  // 'n/a'
+repo.has('db.host')            // true
+repo.set('db.name', 'myapp')   // creates nested key
+repo.all()                     // entire data object
+```
+
+`set()` silently ignores keys containing `__proto__`, `constructor`, or `prototype`.
+
+---
+
+## `dd()` / `dump()`
+
+Debug helpers inspired by Laravel.
+
+```ts
+import { dd, dump } from '@rudderjs/core'
+
+// dump() — pretty-prints and continues
+dump({ user, session })
+dump(req.body, req.headers)   // multiple args supported
+
+// dd() — pretty-prints then terminates the process
+dd(req.body)
+```
+
+Both format arguments with `JSON.stringify` at 2-space indent. `dd()` calls `process.exit(1)` — development use only.
+
+---
+
+## `env()`
+
+Read a string environment variable.
+
+```ts
+import { env } from '@rudderjs/support'
+
+env('APP_NAME', 'RudderJS')   // → 'RudderJS'
+env('APP_ENV')                // throws if missing and no fallback
+```
+
+---
+
+## `Env`
+
+Type-safe access to `process.env`.
+
+```ts
+import { Env } from '@rudderjs/support'
+
+Env.get('APP_NAME', 'RudderJS')       // string  (throws if missing and no fallback)
+Env.getNumber('PORT', 3000)           // number
+Env.getBool('APP_DEBUG', false)       // boolean — case-insensitive 'true' | '1' → true
+Env.has('REDIS_URL')                  // boolean
+```
+
+| Method | Return | Description |
+|---|---|---|
+| `get(key, fallback?)` | `string` | Returns the value or fallback. Throws if both are absent. |
+| `getNumber(key, fallback?)` | `number` | Coerces to number. Throws if absent or NaN. |
+| `getBool(key, fallback?)` | `boolean` | Case-insensitive `'true'` / `'1'` → `true`; everything else → `false`. |
+| `has(key)` | `boolean` | `true` if the variable is set in `process.env`. |
+
+---
+
+## `defineEnv()`
+
+Validate environment variables at startup using a Zod schema. Throws with a clear error listing all missing/invalid keys before the application boots.
+
+```ts
+import { defineEnv } from '@rudderjs/support'
+import { z } from 'zod'
+
+export const env = defineEnv(z.object({
+  DATABASE_URL: z.string().url(),
+  PORT:         z.coerce.number().default(3000),
+  APP_DEBUG:    z.enum(['true', 'false']).transform(v => v === 'true').default('false'),
+}))
+
+env.PORT      // number
+env.APP_DEBUG // boolean
+```
+
+---
+
+## `Collection<T>`
+
+Fluent, typed wrapper around arrays — inspired by Laravel Collections.
+
+```ts
+import { Collection } from '@rudderjs/support'
+
+const users = Collection.of([
+  { id: 1, name: 'Alice', role: 'admin' },
+  { id: 2, name: 'Bob',   role: 'user' },
+  { id: 3, name: 'Carol', role: 'admin' },
+])
+
+users.filter(u => u.role === 'admin').pluck('name').toArray()  // ['Alice', 'Carol']
+users.groupBy('role')   // { admin: [...], user: [...] }
+users.chunk(2).toArray()  // [[...], [...]]
+users.partition(u => u.role === 'admin')  // [Collection<admin>, Collection<user>]
+```
+
+**Core**
+
+| Method | Description |
+|---|---|
+| `all()` | Underlying array. |
+| `count()` | Number of items. |
+| `first(fn?)` | First item (or first matching if `fn` given). |
+| `last(fn?)` | Last item (or last matching if `fn` given). |
+| `isEmpty()` | `true` when empty. |
+| `isNotEmpty()` | `true` when not empty. |
+| `each(fn)` | Iterate; returns `this`. |
+| `toArray()` | Shallow copy. |
+| `toJSON()` | Returns `T[]` — `JSON.stringify` works correctly. |
+
+**Transform**
+
+| Method | Description |
+|---|---|
+| `map<U>(fn)` | Transform each item; returns `Collection<U>`. |
+| `flatMap<U>(fn)` | Map then flatten one level. |
+| `filter(fn)` | Keep matching items. |
+| `reject(fn)` | Remove matching items (inverse of `filter`). |
+| `pluck(key)` | Extract a single field from each item. |
+| `mapSpread<U>(fn)` | Spread each item as args to `fn` (useful for tuples). |
+
+**Search**
+
+| Method | Description |
+|---|---|
+| `find(fn)` | First matching item or `undefined`. |
+| `contains(fn\|value)` | `true` if predicate matches or value is present. |
+| `sole(fn?)` | Single matching item — throws if 0 or >1 found. |
+
+**Grouping**
+
+| Method | Description |
+|---|---|
+| `groupBy(key\|fn)` | Groups into `Record<string, T[]>`. |
+| `keyBy(key\|fn)` | Index by key — returns `Record<string, T>`. Last write wins. |
+| `mapWithKeys(fn)` | Transform to `Record<string, V>` via `fn` returning `[key, value]`. |
+
+**Splitting**
+
+| Method | Description |
+|---|---|
+| `chunk(size)` | Split into `Collection<T[]>` of fixed size. |
+| `splitIn(n)` | Split into exactly `n` roughly-equal groups. |
+| `partition(fn)` | Split into `[passing, failing]` tuple of collections. |
+| `sliding(size, step?)` | Overlapping windows of `size`. |
+
+**Combination**
+
+| Method | Description |
+|---|---|
+| `zip(other)` | Pair items with another array/collection (shortest wins). |
+| `crossJoin(other)` | Cartesian product with another array/collection. |
+| `combine(values)` | Use this collection as keys, `values` as values → `Record<string, V>`. |
+
+**Conditional / Pipe**
+
+| Method | Description |
+|---|---|
+| `when(cond, fn, otherwise?)` | Apply `fn` if condition is truthy. |
+| `unless(cond, fn, otherwise?)` | Apply `fn` if condition is falsy. |
+| `pipe(fn)` | Pass collection through `fn`, return result (break the chain). |
+| `tap(fn)` | Side-effect — calls `fn(this)` then returns `this`. |
+
+---
+
+---
+
+## `Str`
+
+30+ static string helpers — case conversion, truncation, search, extraction, masking, pluralisation, and generation.
+
+```ts
+import { Str } from '@rudderjs/support'
+
+Str.camel('hello_world')       // 'helloWorld'
+Str.snake('helloWorld')        // 'hello_world'
+Str.kebab('helloWorld')        // 'hello-world'
+Str.studly('hello_world')      // 'HelloWorld'
+Str.headline('user_profile')   // 'User Profile'
+Str.slug('Hello World!')       // 'hello-world'
+
+Str.limit('The quick brown fox', 10)          // 'The quick...'
+Str.excerpt('The quick brown fox', 'quick')   // 'The quick brown fox'
+Str.mask('4111111111111111', '*', 0, 12)      // '************1111'
+
+Str.before('user@example.com', '@')    // 'user'
+Str.after('user@example.com', '@')     // 'example.com'
+Str.between('<tag>content</tag>', '<tag>', '</tag>')  // 'content'
+
+Str.plural('post')       // 'posts'
+Str.plural('post', 1)    // 'post'
+Str.singular('posts')    // 'post'
+
+Str.uuid()               // 'f47ac10b-...'
+Str.random(16)           // 'aB3xK9mZ...'
+Str.password(32)         // cryptographically random password
+```
+
+| Category | Methods |
+|---|---|
+| Case | `camel`, `snake`, `kebab`, `studly`, `title`, `headline` |
+| Truncation | `limit`, `words`, `excerpt` |
+| Search | `contains`, `containsAll`, `startsWith`, `endsWith` |
+| Extraction | `before`, `beforeLast`, `after`, `afterLast`, `between` |
+| Replacement | `replaceFirst`, `replaceLast` |
+| Padding | `padLeft`, `padRight`, `padBoth` |
+| Whitespace | `squish`, `trim` |
+| Masking | `mask` |
+| Normalisation | `ascii`, `slug` |
+| Identification | `uuid`, `isUuid`, `isUlid` |
+| Generation | `random`, `password` |
+| Pluralisation | `plural`, `singular` |
+
+---
+
+## `Num`
+
+Static numeric helpers — formatting, abbreviation, ordinals, and more.
+
+```ts
+import { Num } from '@rudderjs/support'
+
+Num.format(1234567.89, 2)          // '1,234,567.89'
+Num.currency(9.99)                 // '$9.99'
+Num.currency(9.99, 'EUR', 'de-DE') // '9,99 €'
+Num.percentage(73.5, 1)            // '73.5%'
+Num.fileSize(1536)                 // '1.50 KB'
+Num.abbreviate(1_500_000)          // '1.5M'
+Num.ordinal(22)                    // '22nd'
+Num.clamp(150, 0, 100)             // 100
+Num.trim(1.5000)                   // '1.5'
+Num.spell(42)                      // 'forty-two'
+Num.spell(1_001)                   // 'one thousand one'
+```
+
+| Method | Description |
+|---|---|
+| `format(n, decimals?, locale?)` | Locale-aware number with separators. |
+| `currency(n, currency?, locale?)` | Currency string via `Intl.NumberFormat`. |
+| `percentage(n, decimals?, locale?)` | `n` as a percentage (`50` → `'50%'`). |
+| `fileSize(bytes, precision?)` | Human-readable file size (`1536` → `'1.50 KB'`). |
+| `abbreviate(n, precision?)` | Short form (`1_500_000` → `'1.5M'`). |
+| `ordinal(n)` | Ordinal suffix (`1` → `'1st'`, `22` → `'22nd'`). |
+| `clamp(n, min, max)` | Clamp to range. |
+| `trim(n, decimals?)` | Remove trailing zeros (`1.500` → `'1.5'`). |
+| `spell(n)` | Integer to English words (`42` → `'forty-two'`). |
+
+---
+
+## Helper Functions
+
+```ts
+import { sleep, ucfirst, pick, omit, tap, deepClone, isObject, toSnakeCase, toCamelCase } from '@rudderjs/support'
+
+await sleep(500)
+
+ucfirst('hello world')                                    // 'Hello world'
+toSnakeCase('fooBarBaz')                                  // 'foo_bar_baz'
+toCamelCase('foo_bar_baz')                                // 'fooBarBaz'
+
+pick({ id: 1, name: 'A', secret: 'x' }, ['id', 'name'])  // { id: 1, name: 'A' }
+omit({ id: 1, secret: 'x' }, ['secret'])                  // { id: 1 }
+
+tap(new Map(), m => m.set('key', 1))                      // returns the Map
+deepClone({ nested: { value: 1 } })                       // deep copy via JSON round-trip
+
+isObject({})          // true
+isObject(new Date())  // false — only plain objects pass
+isObject([])          // false
+isObject(null)        // false
+```
+
+| Function | Description |
+|---|---|
+| `sleep(ms)` | Resolves after `ms` milliseconds. |
+| `ucfirst(str)` | Capitalises the first character. |
+| `toSnakeCase(str)` | `camelCase` / `PascalCase` → `snake_case`. |
+| `toCamelCase(str)` | `snake_case` → `camelCase`. |
+| `pick(obj, keys)` | New object with only the specified keys. |
+| `omit(obj, keys)` | New object with the specified keys removed. |
+| `tap(value, fn)` | Calls `fn(value)` and returns `value`. |
+| `deepClone(value)` | Deep clone via JSON round-trip. |
+| `isObject(value)` | `true` for plain objects only — `false` for `Date`, `Map`, arrays, `null`. |
+
+---
+
+## Notes
+
+- All exports are re-exported from `@rudderjs/core` — you rarely need to import `@rudderjs/support` directly.
+- `defineEnv()` validates eagerly at module evaluation time — failures surface at boot.
+- `dd()` calls `process.exit(1)` — development use only.
+- `resolveOptionalPeer()` resolves optional peer packages from the app root — used internally by adapters.

package/dist/collection.d.ts

@@ -0,0 +1,86 @@
+export declare class Collection<T> {
+    private items;
+    constructor(items?: T[]);
+    static of<T>(items: T[]): Collection<T>;
+    all(): T[];
+    count(): number;
+    first(fn?: (item: T) => boolean): T | undefined;
+    last(fn?: (item: T) => boolean): T | undefined;
+    isEmpty(): boolean;
+    isNotEmpty(): boolean;
+    each(fn: (item: T, index: number) => void): this;
+    map<U>(fn: (item: T, index: number) => U): Collection<U>;
+    flatMap<U>(fn: (item: T, index: number) => U[]): Collection<U>;
+    filter(fn: (item: T) => boolean): Collection<T>;
+    reject(fn: (item: T) => boolean): Collection<T>;
+    pluck<K extends keyof T>(key: K): Collection<T[K]>;
+    find(fn: (item: T) => boolean): T | undefined;
+    contains(fn: ((item: T) => boolean) | T): boolean;
+    /**
+     * Return the single matching item. Throws if 0 or more than 1 item matches.
+     */
+    sole(fn?: (item: T) => boolean): T;
+    groupBy<K extends keyof T>(key: K | ((item: T) => string)): Record<string, T[]>;
+    /** Index items by a key or resolver — last write wins on collision. */
+    keyBy<K extends keyof T>(key: K | ((item: T) => string)): Record<string, T>;
+    /** Transform into a key→value record. `fn` returns `[key, value]` for each item. */
+    mapWithKeys<V>(fn: (item: T, index: number) => [string, V]): Record<string, V>;
+    /**
+     * Split into chunks of `size`.
+     * @example collect([1,2,3,4,5]).chunk(2) → [[1,2],[3,4],[5]]
+     */
+    chunk(size: number): Collection<T[]>;
+    /**
+     * Split into exactly `n` roughly-equal groups.
+     * @example collect([1,2,3,4,5]).splitIn(2) → [[1,2,3],[4,5]]
+     */
+    splitIn(n: number): Collection<T[]>;
+    /**
+     * Split into [passing, failing] based on `fn`.
+     * @example collect([1,2,3,4]).partition(n => n % 2 === 0) → [[2,4], [1,3]]
+     */
+    partition(fn: (item: T) => boolean): [Collection<T>, Collection<T>];
+    /**
+     * Sliding window — yields overlapping sub-arrays of `size`.
+     * @example collect([1,2,3,4]).sliding(2) → [[1,2],[2,3],[3,4]]
+     */
+    sliding(size: number, step?: number): Collection<T[]>;
+    /**
+     * Zip this collection with one or more arrays/collections (shortest wins).
+     * @example collect([1,2]).zip(['a','b']) → [[1,'a'],[2,'b']]
+     */
+    zip<U>(other: U[] | Collection<U>): Collection<[T, U]>;
+    /**
+     * Cross-join with another array/collection — returns the cartesian product.
+     * @example collect([1,2]).crossJoin(['a','b']) → [[1,'a'],[1,'b'],[2,'a'],[2,'b']]
+     */
+    crossJoin<U>(other: U[] | Collection<U>): Collection<[T, U]>;
+    /**
+     * Use this collection as keys and `values` as values — produces a plain object.
+     * @example collect(['name','age']).combine(['Alice', 30]) → { name: 'Alice', age: 30 }
+     */
+    combine<V>(values: V[] | Collection<V>): Record<string, V>;
+    /**
+     * Map where each item is spread as individual arguments to `fn`.
+     * Useful for tuple collections.
+     * @example collect([[1,'a'],[2,'b']]).mapSpread((n, s) => `${n}-${s}`) → ['1-a','2-b']
+     */
+    mapSpread<U>(fn: (...args: unknown[]) => U): Collection<U>;
+    /** Apply `fn` to this collection if `condition` is truthy — chainable. */
+    when(condition: boolean | ((c: Collection<T>) => boolean), fn: (c: Collection<T>) => Collection<T>, otherwise?: (c: Collection<T>) => Collection<T>): Collection<T>;
+    /** Apply `fn` to this collection if `condition` is falsy — chainable. */
+    unless(condition: boolean | ((c: Collection<T>) => boolean), fn: (c: Collection<T>) => Collection<T>, otherwise?: (c: Collection<T>) => Collection<T>): Collection<T>;
+    /**
+     * Pass this collection through a callback and return the result.
+     * Useful for breaking out of method chains.
+     */
+    pipe<U>(fn: (collection: Collection<T>) => U): U;
+    /**
+     * Tap into the chain for side-effects — returns `this`.
+     * @example collect([1,2,3]).tap(c => console.log(c.count())).map(...)
+     */
+    tap(fn: (collection: Collection<T>) => void): this;
+    toArray(): T[];
+    toJSON(): T[];
+}
+//# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}

package/dist/collection.js

@@ -0,0 +1,228 @@
+// ─── Collection ────────────────────────────────────────────
+export class Collection {
+    items;
+    constructor(items = []) {
+        this.items = [...items];
+    }
+    static of(items) {
+        return new Collection(items);
+    }
+    // ── Core ─────────────────────────────────────────────────
+    all() {
+        return this.items;
+    }
+    count() {
+        return this.items.length;
+    }
+    first(fn) {
+        return fn ? this.items.find(fn) : this.items[0];
+    }
+    last(fn) {
+        if (fn) {
+            const filtered = this.items.filter(fn);
+            return filtered[filtered.length - 1];
+        }
+        return this.items[this.items.length - 1];
+    }
+    isEmpty() {
+        return this.items.length === 0;
+    }
+    isNotEmpty() {
+        return this.items.length > 0;
+    }
+    // ── Iteration ────────────────────────────────────────────
+    each(fn) {
+        this.items.forEach(fn);
+        return this;
+    }
+    // ── Transform ────────────────────────────────────────────
+    map(fn) {
+        return new Collection(this.items.map(fn));
+    }
+    flatMap(fn) {
+        return new Collection(this.items.flatMap(fn));
+    }
+    filter(fn) {
+        return new Collection(this.items.filter(fn));
+    }
+    reject(fn) {
+        return new Collection(this.items.filter(item => !fn(item)));
+    }
+    pluck(key) {
+        return new Collection(this.items.map(item => item[key]));
+    }
+    // ── Search ───────────────────────────────────────────────
+    find(fn) {
+        return this.items.find(fn);
+    }
+    contains(fn) {
+        if (typeof fn === 'function')
+            return this.items.some(fn);
+        return this.items.includes(fn);
+    }
+    /**
+     * Return the single matching item. Throws if 0 or more than 1 item matches.
+     */
+    sole(fn) {
+        const filtered = fn ? this.items.filter(fn) : this.items;
+        if (filtered.length === 0)
+            throw new Error('[Collection] sole() found no matching items.');
+        if (filtered.length > 1)
+            throw new Error(`[Collection] sole() found ${filtered.length} items — expected exactly 1.`);
+        return filtered[0];
+    }
+    // ── Grouping ─────────────────────────────────────────────
+    groupBy(key) {
+        return this.items.reduce((acc, item) => {
+            const group = typeof key === 'function' ? key(item) : String(item[key]);
+            acc[group] = [...(acc[group] ?? []), item];
+            return acc;
+        }, {});
+    }
+    /** Index items by a key or resolver — last write wins on collision. */
+    keyBy(key) {
+        const result = {};
+        for (const item of this.items) {
+            const k = typeof key === 'function' ? key(item) : String(item[key]);
+            result[k] = item;
+        }
+        return result;
+    }
+    /** Transform into a key→value record. `fn` returns `[key, value]` for each item. */
+    mapWithKeys(fn) {
+        const result = {};
+        for (let i = 0; i < this.items.length; i++) {
+            const [k, v] = fn(this.items[i], i);
+            result[k] = v;
+        }
+        return result;
+    }
+    // ── Splitting ────────────────────────────────────────────
+    /**
+     * Split into chunks of `size`.
+     * @example collect([1,2,3,4,5]).chunk(2) → [[1,2],[3,4],[5]]
+     */
+    chunk(size) {
+        if (size < 1)
+            throw new Error('[Collection] chunk() size must be >= 1.');
+        const chunks = [];
+        for (let i = 0; i < this.items.length; i += size) {
+            chunks.push(this.items.slice(i, i + size));
+        }
+        return new Collection(chunks);
+    }
+    /**
+     * Split into exactly `n` roughly-equal groups.
+     * @example collect([1,2,3,4,5]).splitIn(2) → [[1,2,3],[4,5]]
+     */
+    splitIn(n) {
+        return this.chunk(Math.ceil(this.items.length / n));
+    }
+    /**
+     * Split into [passing, failing] based on `fn`.
+     * @example collect([1,2,3,4]).partition(n => n % 2 === 0) → [[2,4], [1,3]]
+     */
+    partition(fn) {
+        const pass = [];
+        const fail = [];
+        for (const item of this.items) {
+            ;
+            (fn(item) ? pass : fail).push(item);
+        }
+        return [new Collection(pass), new Collection(fail)];
+    }
+    /**
+     * Sliding window — yields overlapping sub-arrays of `size`.
+     * @example collect([1,2,3,4]).sliding(2) → [[1,2],[2,3],[3,4]]
+     */
+    sliding(size, step = 1) {
+        const result = [];
+        for (let i = 0; i <= this.items.length - size; i += step) {
+            result.push(this.items.slice(i, i + size));
+        }
+        return new Collection(result);
+    }
+    // ── Combination ──────────────────────────────────────────
+    /**
+     * Zip this collection with one or more arrays/collections (shortest wins).
+     * @example collect([1,2]).zip(['a','b']) → [[1,'a'],[2,'b']]
+     */
+    zip(other) {
+        const arr = other instanceof Collection ? other.all() : other;
+        const len = Math.min(this.items.length, arr.length);
+        const result = [];
+        for (let i = 0; i < len; i++)
+            result.push([this.items[i], arr[i]]);
+        return new Collection(result);
+    }
+    /**
+     * Cross-join with another array/collection — returns the cartesian product.
+     * @example collect([1,2]).crossJoin(['a','b']) → [[1,'a'],[1,'b'],[2,'a'],[2,'b']]
+     */
+    crossJoin(other) {
+        const arr = other instanceof Collection ? other.all() : other;
+        const result = [];
+        for (const a of this.items) {
+            for (const b of arr)
+                result.push([a, b]);
+        }
+        return new Collection(result);
+    }
+    /**
+     * Use this collection as keys and `values` as values — produces a plain object.
+     * @example collect(['name','age']).combine(['Alice', 30]) → { name: 'Alice', age: 30 }
+     */
+    combine(values) {
+        const vals = values instanceof Collection ? values.all() : values;
+        const result = {};
+        for (let i = 0; i < this.items.length; i++) {
+            result[String(this.items[i])] = vals[i];
+        }
+        return result;
+    }
+    /**
+     * Map where each item is spread as individual arguments to `fn`.
+     * Useful for tuple collections.
+     * @example collect([[1,'a'],[2,'b']]).mapSpread((n, s) => `${n}-${s}`) → ['1-a','2-b']
+     */
+    mapSpread(fn) {
+        return new Collection(this.items.map(item => fn(...(Array.isArray(item) ? item : [item]))));
+    }
+    // ── Conditional / Pipe ───────────────────────────────────
+    /** Apply `fn` to this collection if `condition` is truthy — chainable. */
+    when(condition, fn, otherwise) {
+        const cond = typeof condition === 'function' ? condition(this) : condition;
+        if (cond)
+            return fn(this);
+        if (otherwise)
+            return otherwise(this);
+        return this;
+    }
+    /** Apply `fn` to this collection if `condition` is falsy — chainable. */
+    unless(condition, fn, otherwise) {
+        return this.when(typeof condition === 'function' ? (c) => !condition(c) : !condition, fn, otherwise);
+    }
+    /**
+     * Pass this collection through a callback and return the result.
+     * Useful for breaking out of method chains.
+     */
+    pipe(fn) {
+        return fn(this);
+    }
+    /**
+     * Tap into the chain for side-effects — returns `this`.
+     * @example collect([1,2,3]).tap(c => console.log(c.count())).map(...)
+     */
+    tap(fn) {
+        fn(this);
+        return this;
+    }
+    // ── Serialisation ────────────────────────────────────────
+    toArray() {
+        return [...this.items];
+    }
+    toJSON() {
+        return this.items;
+    }
+}
+//# sourceMappingURL=collection.js.map