@pithos/core 2.0.0

package/dist/kanon/types/wrappers.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Specialized types for V3 schema wrappers (nullable, optional, default, readonly, lazy).
+ *
+ * @since 2.0.0
+ */
+import { Schema, GenericSchema, Infer, SchemaWrapperType } from "./base";
+/**
+ * Schema for nullable values.
+ *
+ * @template Inner - The inner schema type
+ * @since 2.0.0
+ */
+export type NullableSchema<Inner extends GenericSchema> = Schema<Infer<Inner> | null> & {
+    type: "nullable";
+    innerSchema: Inner;
+};
+/**
+ * Schema for optional values.
+ *
+ * @template Inner - The inner schema type
+ * @since 2.0.0
+ */
+export type OptionalSchema<Inner extends GenericSchema> = Schema<Infer<Inner> | undefined> & {
+    type: "optional";
+    innerSchema: Inner;
+};
+/**
+ * Schema for nullish values (null or undefined).
+ *
+ * @template Inner - The inner schema type
+ * @since 2.0.0
+ */
+export type NullishSchema<Inner extends GenericSchema> = Schema<Infer<Inner> | null | undefined> & {
+    type: "nullish";
+    innerSchema: Inner;
+};
+/**
+ * Schema with default value.
+ *
+ * @template Inner - The inner schema type
+ * @since 2.0.0
+ */
+export type DefaultSchema<Inner extends GenericSchema> = Schema<Infer<Inner>> & {
+    type: "default";
+    innerSchema: Inner;
+    defaultValue: Infer<Inner> | (() => Infer<Inner>);
+};
+/**
+ * Schema for readonly values.
+ *
+ * @template Inner - The inner schema type
+ * @since 2.0.0
+ */
+export type ReadonlySchema<Inner extends GenericSchema> = Schema<Readonly<Infer<Inner>>> & {
+    type: "readonly";
+    innerSchema: Inner;
+};
+/**
+ * Schema for lazy evaluation.
+ *
+ * @template Value - The value type
+ * @since 2.0.0
+ */
+export type LazySchema<Value> = Schema<Value> & {
+    type: "lazy";
+    getter: () => Schema<Value>;
+};
+/**
+ * Extracts the inner schema type from a wrapper schema.
+ *
+ * @template S - The wrapper schema type
+ * @returns The inner schema type, or never if not a wrapper
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * type Inner = UnwrapSchema<NullableSchema<StringSchema>>; // StringSchema
+ * type Inner2 = UnwrapSchema<DefaultSchema<NumberSchema>>; // NumberSchema
+ * ```
+ */
+export type UnwrapSchema<S> = S extends {
+    innerSchema: infer I;
+} ? I extends GenericSchema ? I : never : S extends {
+    getter: () => infer G;
+} ? G extends Schema<infer V> ? Schema<V> : never : never;
+/**
+ * Checks if a schema is a wrapper schema.
+ *
+ * @template S - The schema type to check
+ * @returns true if the schema is a wrapper, false otherwise
+ * @since 2.0.0
+ */
+export type IsWrapper<S> = S extends {
+    type: SchemaWrapperType;
+} ? true : false;
+//# sourceMappingURL=wrappers.d.ts.map

package/dist/kanon/types/wrappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrappers.d.ts","sourceRoot":"","sources":["../../../src/kanon/types/wrappers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,aAAa,IAAI,MAAM,CAC9D,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI,CACpB,GAAG;IACF,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,KAAK,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,aAAa,IAAI,MAAM,CAC9D,KAAK,CAAC,KAAK,CAAC,GAAG,SAAS,CACzB,GAAG;IACF,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,KAAK,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,aAAa,IAAI,MAAM,CAC7D,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,SAAS,CAChC,GAAG;IACF,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,KAAK,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,aAAa,IAAI,MAAM,CAC7D,KAAK,CAAC,KAAK,CAAC,CACb,GAAG;IACF,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,KAAK,CAAC;IACnB,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;CACnD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,aAAa,IAAI,MAAM,CAC9D,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CACvB,GAAG;IACF,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,KAAK,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,WAAW,EAAE,MAAM,CAAC,CAAA;CAAE,GAC5D,CAAC,SAAS,aAAa,GACrB,CAAC,GACD,KAAK,GACP,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,MAAM,CAAC,CAAA;CAAE,GACjC,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,GACvB,MAAM,CAAC,CAAC,CAAC,GACT,KAAK,GACP,KAAK,CAAC;AAEZ;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAAG,IAAI,GAAG,KAAK,CAAC"}

package/dist/kanon/types/wrappers.js

@@ -0,0 +1,7 @@
+/**
+ * Specialized types for V3 schema wrappers (nullable, optional, default, readonly, lazy).
+ *
+ * @since 2.0.0
+ */
+export {};
+//# sourceMappingURL=wrappers.js.map

package/dist/kanon/types/wrappers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrappers.js","sourceRoot":"","sources":["../../../src/kanon/types/wrappers.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/kanon/validation.d.ts

@@ -0,0 +1,64 @@
+import { Schema } from "./types/base";
+/**
+ * Result type for safe parsing operations.
+ *
+ * @template T - The type of the parsed data.
+ * @since 2.0.0
+ */
+export type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Kanon V3 lightweight validation helpers (Zod-like ergonomics, minimal surface).
+ *
+ * @since 2.0.0
+ */
+export declare const validation: {
+    /**
+     * Parses a value and throws on failure.
+     *
+     * @template T - The expected output type.
+     * @param schema - The Kanon schema to validate against.
+     * @param value - The value to validate.
+     * @returns The validated and possibly coerced value.
+     * @throws {Error} When validation fails.
+     * @since 2.0.0
+     */
+    parse<T>(schema: Schema<T>, value: unknown): T;
+    /**
+     * Parses a value and returns a discriminated result.
+     *
+     * @template T - The expected output type.
+     * @param schema - The Kanon schema to validate against.
+     * @param value - The value to validate.
+     * @returns A `SafeParseResult` with `success` flag and data or error.
+     * @since 2.0.0
+     */
+    safeParse<T>(schema: Schema<T>, value: unknown): SafeParseResult<T>;
+    /**
+     * Async variant of `parse`, kept for API parity (logic stays sync).
+     *
+     * @template T - The expected output type.
+     * @param schema - The Kanon schema to validate against.
+     * @param value - The value to validate.
+     * @returns Promise resolving to the validated value.
+     * @throws {Error} When validation fails.
+     * @since 2.0.0
+     */
+    parseAsync<T>(schema: Schema<T>, value: unknown): Promise<T>;
+    /**
+     * Async variant of `safeParse`, kept for API parity (logic stays sync).
+     *
+     * @template T - The expected output type.
+     * @param schema - The Kanon schema to validate against.
+     * @param value - The value to validate.
+     * @returns Promise resolving to a `SafeParseResult`.
+     * @since 2.0.0
+     */
+    safeParseAsync<T>(schema: Schema<T>, value: unknown): Promise<SafeParseResult<T>>;
+};
+//# sourceMappingURL=validation.d.ts.map

package/dist/kanon/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/kanon/validation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC1B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,UAAU;IACrB;;;;;;;;;OASG;UACG,CAAC,UAAU,MAAM,CAAC,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC;IAM9C;;;;;;;;OAQG;cACO,CAAC,UAAU,MAAM,CAAC,CAAC,CAAC,SAAS,OAAO,GAAG,eAAe,CAAC,CAAC,CAAC;IAInE;;;;;;;;;OASG;eACc,CAAC,UAAU,MAAM,CAAC,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIlE;;;;;;;;OAQG;mBACkB,CAAC,UACZ,MAAM,CAAC,CAAC,CAAC,SACV,OAAO,GACb,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAG/B,CAAC"}

package/dist/kanon/validation.js

@@ -0,0 +1,62 @@
+import { parse } from "./core/parser";
+/**
+ * Kanon V3 lightweight validation helpers (Zod-like ergonomics, minimal surface).
+ *
+ * @since 2.0.0
+ */
+export const validation = {
+    /**
+     * Parses a value and throws on failure.
+     *
+     * @template T - The expected output type.
+     * @param schema - The Kanon schema to validate against.
+     * @param value - The value to validate.
+     * @returns The validated and possibly coerced value.
+     * @throws {Error} When validation fails.
+     * @since 2.0.0
+     */
+    parse(schema, value) {
+        const result = parse(schema, value);
+        if (result.success)
+            return result.data;
+        throw new Error(result.error);
+    },
+    /**
+     * Parses a value and returns a discriminated result.
+     *
+     * @template T - The expected output type.
+     * @param schema - The Kanon schema to validate against.
+     * @param value - The value to validate.
+     * @returns A `SafeParseResult` with `success` flag and data or error.
+     * @since 2.0.0
+     */
+    safeParse(schema, value) {
+        return parse(schema, value);
+    },
+    /**
+     * Async variant of `parse`, kept for API parity (logic stays sync).
+     *
+     * @template T - The expected output type.
+     * @param schema - The Kanon schema to validate against.
+     * @param value - The value to validate.
+     * @returns Promise resolving to the validated value.
+     * @throws {Error} When validation fails.
+     * @since 2.0.0
+     */
+    async parseAsync(schema, value) {
+        return this.parse(schema, value);
+    },
+    /**
+     * Async variant of `safeParse`, kept for API parity (logic stays sync).
+     *
+     * @template T - The expected output type.
+     * @param schema - The Kanon schema to validate against.
+     * @param value - The value to validate.
+     * @returns Promise resolving to a `SafeParseResult`.
+     * @since 2.0.0
+     */
+    async safeParseAsync(schema, value) {
+        return this.safeParse(schema, value);
+    },
+};
+//# sourceMappingURL=validation.js.map

package/dist/kanon/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/kanon/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAatC;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB;;;;;;;;;OASG;IACH,KAAK,CAAI,MAAiB,EAAE,KAAc;QACxC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACpC,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC,IAAI,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,CAAI,MAAiB,EAAE,KAAc;QAC5C,OAAO,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,UAAU,CAAI,MAAiB,EAAE,KAAc;QACnD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,cAAc,CAClB,MAAiB,EACjB,KAAc;QAEd,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;CACF,CAAC"}

package/dist/sphalma/error-factory.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A structured error with a numeric code and type for easy identification.
+ * Designed for tree-shaking: only imported if used.
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * throw new CodedError(101, "Animation", { id: "fade" });
+ * // Error: [Animation:101]
+ * ```
+ */
+export declare class CodedError extends Error {
+    readonly code: number;
+    readonly type: string;
+    readonly key: string;
+    readonly details?: unknown;
+    constructor(code: number, type: string, details?: unknown);
+}
+/**
+ * Creates a factory function for generating CodedError instances of a specific type.
+ * The factory is tree-shakable: if not imported, it won't be bundled.
+ * @template Code - The numeric error codes allowed for this factory.
+ * @param errorType - The error type/category (e.g., "Animation", "Semaphore").
+ * @returns A factory function that creates CodedError instances.
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * const createAnimationError = createErrorFactory<100 | 101 | 102>("Animation");
+ * throw createAnimationError(101, { id: "missing" });
+ * ```
+ */
+export declare function createErrorFactory<Code extends number>(errorType: string): (code: Code, details?: unknown) => CodedError;
+//# sourceMappingURL=error-factory.d.ts.map

package/dist/sphalma/error-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-factory.d.ts","sourceRoot":"","sources":["../../src/sphalma/error-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAY1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,SAAS,MAAM,EAAE,SAAS,EAAE,MAAM,IAC/D,MAAM,IAAI,EAAE,UAAU,OAAO,KAAG,UAAU,CAGnD"}

package/dist/sphalma/error-factory.js

@@ -0,0 +1,42 @@
+/**
+ * A structured error with a numeric code and type for easy identification.
+ * Designed for tree-shaking: only imported if used.
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * throw new CodedError(101, "Animation", { id: "fade" });
+ * // Error: [Animation:101]
+ * ```
+ */
+export class CodedError extends Error {
+    constructor(code, type, details) {
+        const key = `${type}:0x${code.toString(16)}`;
+        super(`[${key}]`);
+        this.code = code;
+        this.type = type;
+        this.key = key;
+        this.details = details;
+        this.name = "CodedError";
+        // Maintain prototype chain for instanceof checks
+        Object.setPrototypeOf(this, CodedError.prototype);
+    }
+}
+/**
+ * Creates a factory function for generating CodedError instances of a specific type.
+ * The factory is tree-shakable: if not imported, it won't be bundled.
+ * @template Code - The numeric error codes allowed for this factory.
+ * @param errorType - The error type/category (e.g., "Animation", "Semaphore").
+ * @returns A factory function that creates CodedError instances.
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * const createAnimationError = createErrorFactory<100 | 101 | 102>("Animation");
+ * throw createAnimationError(101, { id: "missing" });
+ * ```
+ */
+export function createErrorFactory(errorType) {
+    return (code, details) => {
+        return new CodedError(code, errorType, details);
+    };
+}
+//# sourceMappingURL=error-factory.js.map

package/dist/sphalma/error-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-factory.js","sourceRoot":"","sources":["../../src/sphalma/error-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAMnC,YAAY,IAAY,EAAE,IAAY,EAAE,OAAiB;QACvD,MAAM,GAAG,GAAG,GAAG,IAAI,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QAEzB,iDAAiD;QACjD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAsB,SAAiB;IACvE,OAAO,CAAC,IAAU,EAAE,OAAiB,EAAc,EAAE;QACnD,OAAO,IAAI,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/taphos/array/at.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Returns the item at the given index, allowing for positive and negative integers.
+ *
+ * Negative integers count back from the last item in the array.
+ *
+ * @template T - The type of elements in the array.
+ * @param arr - The array to query.
+ * @param index - The index of the element to return.
+ * @returns The element at the given index, or `undefined` if out of bounds.
+ * @deprecated Use `array.at(index)` directly instead.
+ * Reason: Native equivalent method now available
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/at | Array.at() - MDN}
+ * @see {@link https://caniuse.com/mdn-javascript_builtins_array_at | Browser support - Can I Use}
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const numbers = [1, 2, 3, 4, 5];
+ *
+ * // ❌ Deprecated approach
+ * const first = at(numbers, 0);
+ * console.log(first); // 1
+ *
+ * const last = at(numbers, -1);
+ * console.log(last); // 5
+ *
+ * // ✅ Recommended approach
+ * const firstNative = numbers[0];
+ * console.log(firstNative); // 1
+ *
+ * const lastNative = numbers[numbers.length - 1];
+ * console.log(lastNative); // 5
+ *
+ * // ✅ Modern approach with ES2022
+ * const firstModern = numbers.at(0);
+ * console.log(firstModern); // 1
+ *
+ * const lastModern = numbers.at(-1);
+ * console.log(lastModern); // 5
+ * ```
+ */
+export declare function at<T>(arr: T[], index: number): T | undefined;
+//# sourceMappingURL=at.d.ts.map

package/dist/taphos/array/at.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"at.d.ts","sourceRoot":"","sources":["../../../src/taphos/array/at.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAQ5D"}

package/dist/taphos/array/at.js

@@ -0,0 +1,50 @@
+/**
+ * Returns the item at the given index, allowing for positive and negative integers.
+ *
+ * Negative integers count back from the last item in the array.
+ *
+ * @template T - The type of elements in the array.
+ * @param arr - The array to query.
+ * @param index - The index of the element to return.
+ * @returns The element at the given index, or `undefined` if out of bounds.
+ * @deprecated Use `array.at(index)` directly instead.
+ * Reason: Native equivalent method now available
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/at | Array.at() - MDN}
+ * @see {@link https://caniuse.com/mdn-javascript_builtins_array_at | Browser support - Can I Use}
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const numbers = [1, 2, 3, 4, 5];
+ *
+ * // ❌ Deprecated approach
+ * const first = at(numbers, 0);
+ * console.log(first); // 1
+ *
+ * const last = at(numbers, -1);
+ * console.log(last); // 5
+ *
+ * // ✅ Recommended approach
+ * const firstNative = numbers[0];
+ * console.log(firstNative); // 1
+ *
+ * const lastNative = numbers[numbers.length - 1];
+ * console.log(lastNative); // 5
+ *
+ * // ✅ Modern approach with ES2022
+ * const firstModern = numbers.at(0);
+ * console.log(firstModern); // 1
+ *
+ * const lastModern = numbers.at(-1);
+ * console.log(lastModern); // 5
+ * ```
+ */
+export function at(arr, index) {
+    const len = arr.length;
+    const normalizedIndex = index < 0 ? len + index : index;
+    // Stryker disable next-line ConditionalExpression,LogicalOperator,EqualityOperator: Early return optimization - arr[normalizedIndex] returns undefined for out-of-bounds indices anyway
+    if (normalizedIndex < 0 || normalizedIndex >= len)
+        return undefined;
+    return arr[normalizedIndex];
+}
+//# sourceMappingURL=at.js.map

package/dist/taphos/array/at.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"at.js","sourceRoot":"","sources":["../../../src/taphos/array/at.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,EAAE,CAAI,GAAQ,EAAE,KAAa;IAC3C,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;IACvB,MAAM,eAAe,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;IAExD,wLAAwL;IACxL,IAAI,eAAe,GAAG,CAAC,IAAI,eAAe,IAAI,GAAG;QAAE,OAAO,SAAS,CAAC;IAEpE,OAAO,GAAG,CAAC,eAAe,CAAC,CAAC;AAC9B,CAAC"}

package/dist/taphos/array/compact.d.ts

@@ -0,0 +1,29 @@
+type Truthy<T> = Exclude<T, false | null | 0 | 0n | '' | undefined>;
+/**
+ * Removes all falsy values from an array.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to compact.
+ * @returns A new array with all falsy values removed.
+ * @deprecated Use `array.filter(Boolean)` directly instead.
+ * Reason: Native equivalent method now available
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter | Array.filter() - MDN}
+ * @see {@link https://caniuse.com/mdn-javascript_builtins_array_filter | Browser support - Can I Use}
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const mixed = [1, 0, false, '', 'hello', null, undefined];
+ *
+ * // ❌ Deprecated approach
+ * const compacted = compact(mixed);
+ * console.log(compacted); // [1, 'hello']
+ *
+ * // ✅ Recommended approach
+ * const filtered = mixed.filter(Boolean);
+ * console.log(filtered); // [1, 'hello']
+ * ```
+ */
+export declare function compact<T>(array: readonly T[]): Truthy<T>[];
+export {};
+//# sourceMappingURL=compact.d.ts.map

package/dist/taphos/array/compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../../src/taphos/array/compact.ts"],"names":[],"mappings":"AAAA,KAAK,MAAM,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAY3D"}

package/dist/taphos/array/compact.js

@@ -0,0 +1,37 @@
+/**
+ * Removes all falsy values from an array.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to compact.
+ * @returns A new array with all falsy values removed.
+ * @deprecated Use `array.filter(Boolean)` directly instead.
+ * Reason: Native equivalent method now available
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter | Array.filter() - MDN}
+ * @see {@link https://caniuse.com/mdn-javascript_builtins_array_filter | Browser support - Can I Use}
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const mixed = [1, 0, false, '', 'hello', null, undefined];
+ *
+ * // ❌ Deprecated approach
+ * const compacted = compact(mixed);
+ * console.log(compacted); // [1, 'hello']
+ *
+ * // ✅ Recommended approach
+ * const filtered = mixed.filter(Boolean);
+ * console.log(filtered); // [1, 'hello']
+ * ```
+ */
+export function compact(array) {
+    const result = [];
+    // Stryker disable next-line EqualityOperator: out-of-bounds array[length] is undefined (falsy), always filtered out by the if(item) guard
+    for (let i = 0; i < array.length; i++) {
+        const item = array[i];
+        if (item) {
+            result.push(item);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=compact.js.map

package/dist/taphos/array/compact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact.js","sourceRoot":"","sources":["../../../src/taphos/array/compact.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,OAAO,CAAI,KAAmB;IAC5C,MAAM,MAAM,GAAgB,EAAE,CAAC;IAE/B,0IAA0I;IAC1I,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,CAAC,IAAI,CAAC,IAAiB,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/taphos/array/concat.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Concatenates arrays and values into a new array.
+ *
+ * @template T - The type of elements in the arrays.
+ * @param array - The initial array.
+ * @param values - Additional arrays or values to concatenate.
+ * @returns A new array containing all elements from the input arrays.
+ * @deprecated Use `array.concat()` directly instead.
+ * Reason: Native equivalent method now available
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat | Array.concat() - MDN}
+ * @see {@link https://caniuse.com/mdn-javascript_builtins_array_concat | Browser support - Can I Use}
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const arr1 = [1, 2];
+ * const arr2 = [3, 4];
+ *
+ * // ❌ Deprecated approach
+ * const concatenated = concat(arr1, arr2);
+ * console.log(concatenated); // [1, 2, 3, 4]
+ *
+ * // ✅ Recommended approach
+ * const concatenatedNative = arr1.concat(arr2);
+ * console.log(concatenatedNative); // [1, 2, 3, 4]
+ * ```
+ */
+export declare function concat<T>(array: T[], ...values: (T | T[])[]): T[];
+//# sourceMappingURL=concat.d.ts.map

package/dist/taphos/array/concat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concat.d.ts","sourceRoot":"","sources":["../../../src/taphos/array/concat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEjE"}

package/dist/taphos/array/concat.js

@@ -0,0 +1,31 @@
+/**
+ * Concatenates arrays and values into a new array.
+ *
+ * @template T - The type of elements in the arrays.
+ * @param array - The initial array.
+ * @param values - Additional arrays or values to concatenate.
+ * @returns A new array containing all elements from the input arrays.
+ * @deprecated Use `array.concat()` directly instead.
+ * Reason: Native equivalent method now available
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat | Array.concat() - MDN}
+ * @see {@link https://caniuse.com/mdn-javascript_builtins_array_concat | Browser support - Can I Use}
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const arr1 = [1, 2];
+ * const arr2 = [3, 4];
+ *
+ * // ❌ Deprecated approach
+ * const concatenated = concat(arr1, arr2);
+ * console.log(concatenated); // [1, 2, 3, 4]
+ *
+ * // ✅ Recommended approach
+ * const concatenatedNative = arr1.concat(arr2);
+ * console.log(concatenatedNative); // [1, 2, 3, 4]
+ * ```
+ */
+export function concat(array, ...values) {
+    return array.concat(...values);
+}
+//# sourceMappingURL=concat.js.map

package/dist/taphos/array/concat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concat.js","sourceRoot":"","sources":["../../../src/taphos/array/concat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,MAAM,CAAI,KAAU,EAAE,GAAG,MAAmB;IAC1D,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AACjC,CAAC"}

package/dist/taphos/array/find.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Iterates over elements of collection, returning the first element predicate returns truthy for.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to search.
+ * @param predicate - The function invoked per iteration.
+ * @returns The matched element, or `undefined` if not found.
+ * @deprecated Use `array.find(predicate)` directly instead.
+ * Reason: Native equivalent method now available
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find | Array.find() - MDN}
+ * @see {@link https://caniuse.com/mdn-javascript_builtins_array_find | Browser support - Can I Use}
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { name: 'John', age: 25 },
+ *   { name: 'Jane', age: 30 },
+ *   { name: 'Bob', age: 35 }
+ * ];
+ *
+ * // ❌ Deprecated approach
+ * const found = find(users, user => user.age > 28);
+ * console.log(found); // { name: 'Jane', age: 30 }
+ *
+ * // ✅ Recommended approach
+ * const foundNative = users.find(user => user.age > 28);
+ * console.log(foundNative); // { name: 'Jane', age: 30 }
+ * ```
+ */
+export declare function find<T>(array: T[], predicate: (value: T, index: number, array: T[]) => boolean): T | undefined;
+//# sourceMappingURL=find.d.ts.map

package/dist/taphos/array/find.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/taphos/array/find.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,GAC1D,CAAC,GAAG,SAAS,CAEf"}

package/dist/taphos/array/find.js

@@ -0,0 +1,34 @@
+/**
+ * Iterates over elements of collection, returning the first element predicate returns truthy for.
+ *
+ * @template T - The type of elements in the array.
+ * @param array - The array to search.
+ * @param predicate - The function invoked per iteration.
+ * @returns The matched element, or `undefined` if not found.
+ * @deprecated Use `array.find(predicate)` directly instead.
+ * Reason: Native equivalent method now available
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find | Array.find() - MDN}
+ * @see {@link https://caniuse.com/mdn-javascript_builtins_array_find | Browser support - Can I Use}
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { name: 'John', age: 25 },
+ *   { name: 'Jane', age: 30 },
+ *   { name: 'Bob', age: 35 }
+ * ];
+ *
+ * // ❌ Deprecated approach
+ * const found = find(users, user => user.age > 28);
+ * console.log(found); // { name: 'Jane', age: 30 }
+ *
+ * // ✅ Recommended approach
+ * const foundNative = users.find(user => user.age > 28);
+ * console.log(foundNative); // { name: 'Jane', age: 30 }
+ * ```
+ */
+export function find(array, predicate) {
+    return array.find(predicate);
+}
+//# sourceMappingURL=find.js.map

package/dist/taphos/array/find.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../src/taphos/array/find.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,IAAI,CAClB,KAAU,EACV,SAA2D;IAE3D,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC/B,CAAC"}