queryable-array 1.0.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright © 2026 Kip Price
+
+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,77 @@
+# Queryable Arrays
+
+[![Test Coverage](https://github.com/kipprice/queryable-array/actions/workflows/coverage.yml/badge.svg)](https://github.com/kipprice/queryable-array/actions/workflows/coverage.yml)
+[![Build](https://github.com/kipprice/queryable-array/actions/workflows/build.yml/badge.svg)](https://github.com/kipprice/queryable-array/actions/workflows/build.yml)
+[![Benchmark](https://github.com/kipprice/queryable-array/actions/workflows/benchmark.yml/badge.svg)](https://github.com/kipprice/queryable-array/actions/workflows/benchmark.yml)
+
+
+A lightweight (14kb) TS-first querying language designed to make it easy to work with arrays that need significant filtering, joining, sorting, or mapping. This library has no external dependencies, and performance of the queryable array is within an order of magnitude of standard arrays, ensuring that if you could perform a query via standard array functions, you can probably use a queryable array to do the same, albeit a little more human readable.
+
+## Why use this instead of standard array functions, `lodash`, etc.?
+
+This library has a narrow scope that really optimizes for readability (without sacrificing too much in performance). It is designed for teams that are doing a significant amount of filtering and/or joining in JS / TS code (client-side or server-side) and want the queries they are writing to be somewhat self documenting. For example, consider:
+
+```ts
+const authors = [
+  { id: 'a1', name: 'Kip', contributorSince: '2008-01-01' }, 
+  // ...
+]
+const songs = [
+  { 
+    id: 's1', 
+    name: 'My Song', 
+    tags: [{ id: 't1', label: 'rad'}], 
+    authorIds: ['a1'],
+    lengthInSeconds: 800
+  },
+  // ...
+]
+
+// standard array version
+const radLongSongsWithAuthors = songs
+  .filter((s) => s.length > 500)
+  .filter((s) => s.tags.some((t) => t.name === 'rad'))
+  .map((s) => ({ ...s, authors: s.authorIds.map((aId) => 
+    authors.find((a) => a.id === s.authorId)
+  )}))
+
+// queryable array version
+const queryableSongs = queryable(songs)
+  .where('length').greaterThan(500)
+  .and.where('tags').some('tag').its('label').is('rad')
+  .joinWith(authors).whereMy('authorIds').referencesTheir('id').storedTo('authors')
+```
+
+## How does it work?
+
+Under the hood, a queryable array extends a standard array, so you can still perform standard array functions on it. Any standard array method that would normally return an array (either as a new instance or by modifying the current array) returns a pre-wrapped queryable array so you can continue chaining off of it. A queryable array respects the same behavior as the underlying array methods, swapping in place when the array method would do so.
+
+```ts
+const songs = [
+  { 
+    id: 's1', 
+    name: 'My Song', 
+    tags: [{ id: 't1', label: 'rad'}], 
+    authorId: 'a1',
+    lengthInSeconds: 800
+  },
+  // ...
+]
+
+const tags = songs
+  .flatMap((s) => s.tags)
+  .uniqueBy('id')
+  .where('label').is('rad')
+```
+
+## Types
+
+Everything in the queryable array library is written in Typescript and infers the shape of objects automatically to present appropriate methods and properties depending on where in the chain a given queryable array is. Performing `where` queries are non-modifying, meaning the underlying array wrapped by the queryable array remains as it was even as the queryable array version gets successively more narrowed.
+
+## Bug Reports
+
+Please report any found bugs on the library's GH [Issues](https://github.com/kipprice/queryable-array/issues) page.
+
+## Contributing
+
+If you're interested in helping improve this library, feel free to open a PR against the [repo](https://github.com/kipprice/queryable-array/pulls).

package/dist/index.d.ts

@@ -0,0 +1,414 @@
+export declare interface ArrayQueryClause<T extends Array<unknown>, E extends T extends Array<infer E> ? E : never = T extends Array<infer E> ? E : never, R = QueryClauseResult<T>> extends BaseQueryClause<T, R> {
+    /**
+     * considers this array resolved if at least one element in the array resolves
+     * to true in the subsequent logic calls
+     *
+     * @param   label
+     *          Functionally unused, but allows deeply nested calls to `some` to
+     *          be more human readable by labeling the entity being looped over
+     */
+    some: (label?: string) => UnionToIntersection<QueryClause<E, R>>;
+    /**
+     * considers this array resolved if every element in the array resolves to
+     * true in the subsequent logic calls before including this element into the
+     * query result
+     *
+     * @param   label
+     *          Functionally unused, but allows deeply nested calls to `every` to
+     *          be more human readable by labeling the entity being looped over
+     */
+    every: (label?: string) => UnionToIntersection<QueryClause<E, R>>;
+    /**
+     * determines whether the provided value is findable within the current value
+     * array. Similar to 'is' and 'in', this does a string equality check for
+     * the specified value; if a deep match is required, it's preferred to use
+     * a combination of 'some' / 'every' and 'matches' (or further filtering
+     * logic)
+     *
+     * @param   t
+     *          The element that should be contained within this array
+     */
+    includes: (t: E) => R;
+    /** determins if the array has no elements */
+    isEmpty: () => R;
+}
+
+/**-------------------------------------------------------------------------
+ * BaseQueryClause
+ * -------------------------------------------------------------------------
+ * A foundational object that tracks a current value and creates a set of
+ * resolving functions to determine whether that current value is considered
+ * a match for the query that spawned it.
+ *
+ * A Query Clause can only be resolved once, but depending on the value under
+ * test, it may undergo several chained methods before it is resolved to
+ * narrow the specificity of the query.
+ *
+ * -------------------------------------------------------------------------
+ */
+export declare interface BaseQueryClause<T, R = QueryClauseResult<T>> {
+    /** whether this clause has been resolved. */
+    isResolved: boolean;
+    /** whether this clause will resolve to 'true' for non-matches rather than matches */
+    isNegated: boolean;
+    /** the current value under evaluation */
+    value?: T;
+    /** when resolved, treat a 'false' result as a match and a 'true' result as a non-match */
+    not: QueryClause<T, R>;
+    /**
+     * check for equality between the current value and the provided comparison
+     * value. For objects and arrays, this compares via stringified equality, not
+     * reference equality.
+     **/
+    is: (value: T | null | undefined) => R;
+    /** check for equality between the current value and the provided comparison value; synonym for 'is' */
+    equals: (value: T | null | undefined) => R;
+    /** check for equality between the current value and the provided comparison value; synonym for 'is */
+    eq: (value: T | null | undefined) => R;
+    /** check if the current value is null */
+    isNull: () => R;
+    /** check if the current value is undefined */
+    isUndefined: () => R;
+    /** check if the current value is null or undefined */
+    isNullish: () => R;
+    /**
+     * check if the current value is contained within the provided values. For
+     * objects and aeeats, this compares via stringified equality, not reference
+     * equality
+     */
+    in: (value: T[]) => R;
+    /**
+     * check if the current value, when passed into the provided function,
+     * resolves to 'true'
+     **/
+    satisfies: (fn: (t: T) => boolean) => R;
+}
+
+export declare interface ComparableQueryClause<T extends string | number, R = QueryClauseResult<T>> extends BaseQueryClause<T, R> {
+    /** determines whether the current value is greater than the provided value */
+    gt: (value: T) => R;
+    /** determines whether the current value is greater than the provided value; synonym for 'gt' */
+    greaterThan: (value: T) => R;
+    /** determines whether the current value is greater than or equal to the provided value */
+    gte: (value: T) => R;
+    /** determines whether the current value is greater than or equal to the provided value; synonym for 'gte' */
+    greaterThanOrEqualTo: (value: T) => R;
+    /** determines whether the current value is less than the provided value */
+    lt: (value: T) => R;
+    /** determines whether the current value is less than the provided value; synonym for 'lt' */
+    lessThan: (value: T) => R;
+    /** determines whether the current value is less than or equal to the provided value */
+    lte: (value: T) => R;
+    /** determines whether the current value is less than or equal to the provided value; synonym for 'lte' */
+    lessThanOrEqualTo: (value: T) => R;
+}
+
+export declare type ElemType<T> = T extends Array<infer E> ? E : never;
+
+export declare type Key = string | number | symbol;
+
+export declare type NestedPartial<T> = {
+    [K in keyof T]?: NestedPartial<T[K]>;
+};
+
+export declare interface ObjectQueryClause<T extends object, R = QueryClauseResult<T>> extends BaseQueryClause<T, R> {
+    /**
+     * extracts a particular property from the current value and treats that
+     * value at that property as the new current value for subsequent calls
+     */
+    its: <K extends keyof T>(k: K) => UnionToIntersection<QueryClause<T[K], R>>;
+    /**
+     * determines if the current value contains all of the data specified in
+     * the provided partial value. Unlike `is`, this performs a deep equality
+     * check between two objects
+     */
+    matches: (t: NestedPartial<T>) => R;
+    /**
+     * determines if the current value is an exact match for the provided value.
+     * This is stricter than `matches` in that it requires the provided value to
+     * also be full instance of the model
+     */
+    deepEquals: (t: T) => R;
+    /** determins if the object has no keys */
+    isEmpty: () => R;
+}
+
+export declare const ql: typeof queryable;
+
+/**----------------------------------------------------------------------------
+ * queryable
+ * ----------------------------------------------------------------------------
+ * Augment an array of data elements (or a single data element, which will
+ * subsequently be wrapped in an array) with query helpers that allow for more
+ * human-readable filtering and map logic.
+ *
+ * @param   toBeQueryable
+ *          If an array, augments the array with additional functionality that
+ *          can be called to directly filter the array. If not an array, first
+ *          wraps the element in an array, then augments it to have the same
+ *          query functions.
+ *
+ * @returns An Array-like object that can be used in all places that an array
+ *          can be used, but can also be directly filtered.
+ *
+ * @example
+ * // returns an new array containing just the second element
+ * queryable([{ id: 1 }, { id: 2 }, { id: 3 }])
+ *  .where('id').greaterThan(1)
+ *  .and.where('id').lessThan(3)
+ *  .and.where('id').satisfies((id) => id % 2 === 0)
+ *
+ * -------------------------------------------------------------------------
+ */
+export declare function queryable<T, E extends T extends Array<infer E> ? E : T>(toBeQueryable: T): QueryableArray<E>;
+
+/**-------------------------------------------------------------------------
+ * QueryableArray
+ * -------------------------------------------------------------------------
+ * Helper to be able to take an array of data and turn it into a user-friendly
+ * queryable object. This is an actual class as opposed to a wrapped object
+ * so we can continue to take advantage of native array functionality,
+ *
+ * -------------------------------------------------------------------------
+ */
+export declare class QueryableArray<T> extends Array<T> {
+    protected _currentLogic: "and" | "or";
+    /** the set of currently included elems, if relevant -- used to improve performance of OR queries */
+    protected _currentSet: Set<T>;
+    protected _currentData: T[];
+    protected _originalData: T[];
+    [idx: number]: T;
+    /** ensure that we instantiate intermediate versions of query arrays (e.g.
+     * through .filter or .map) as a straight array instance -- we will always
+     * explicitly wrap the result in a QueryableArray when appropriate */
+    static get [Symbol.species](): ArrayConstructor;
+    get data(): T[];
+    constructor(elements: T[], originalData?: T[], _currentLogic?: "and" | "or", 
+    /** the set of currently included elems, if relevant -- used to improve performance of OR queries */
+    _currentSet?: Set<T>);
+    /**
+     * ensure that we have the elements from _currentData also populated into our
+     * numeric indices, so that you can extract data as you would from a regular
+     * array
+     **/
+    protected _populateInnerStore(): void;
+    /**
+     * get the first element in the query array, based on the current query
+     */
+    get first(): T | undefined;
+    /**
+     * get the last element in the query array, based on the current query
+     */
+    get last(): T | undefined;
+    /**
+     * apply a new query to the array, enusring that only elements that match
+     * both the current query and the new query are included
+     */
+    get and(): this;
+    /**
+     * apply a new query to the array, ensuring that elements that match either
+     * the current query or the new query are included (without duplicates)
+     */
+    get or(): this;
+    /**
+     * Remove any duplicate members of the array, via deep-equality comparison
+     *
+     * @returns This QueryableArray sans duplicate members
+     */
+    unique(): QueryableArray<T>;
+    /**
+     * Remove any members of the array that are considered a duplicate via the
+     * provided key getter.
+     *
+     * @param   keyGetter
+     *          Either a property name or a function that can be used to get the
+     *          value that should be compared for uniqueness
+     *
+     * @returns This QueryableArray sans duplicate members
+     */
+    uniqueBy<X>(keyGetter: keyof T | ((t: T) => X)): QueryableArray<T>;
+    /**
+     * sort the query array by either the value in the specified property or via
+     * a function evaluator.
+     *
+     * @param   sortKeyGetter
+     *          The property or function that can retrieve a sortable value from
+     *          a given element
+     *
+     * @param   direction
+     *          Whether we should perform an ascending or descending search
+     *
+     * @returns A sorted version of this query array
+     */
+    sortBy(sortKeyGetter: keyof T | ((t: T) => string | number), direction?: "asc" | "desc"): QueryableArray<T>;
+    /**
+     * turn this query array into a map, with keys based on the provided key
+     * getter.
+     *
+     * This assumes that the key retrieved is unique for the element in
+     * question; if multiple elements could return the same key, use `groupBy`
+     * instead
+     *
+     * @param   keyGetter
+     *          A function or name of a property that can extract an appropriate
+     *          key for any given element.
+     *
+     * @returns A map of the query array, keyed by the results of the keyGetter
+     */
+    indexBy(keyGetter: keyof T | ((t: T) => Key)): Record<Key, T>;
+    /**
+     * group all elements in the query array by a given key
+     *
+     * @param   keyGetter
+     *          The property name or function to retrieve the value
+     *
+     * @returns A map with keys based on the results of keyGetter and an array
+     *          of values that returned that key
+     */
+    groupBy(keyGetter: keyof T | ((t: T) => Key | Key[])): Record<Key, T[]>;
+    /**
+     * extract inner data from this query array and turn it into a QueryableArray of
+     * its own. Will automatically flatten data if the result of the key getter
+     * is an array.
+     *
+     * @param   keyGetter
+     *          The key to extract to get the appropriate inner data
+     */
+    extract<K extends keyof T, X extends T[K]>(keyGetter: K): QueryableArray<X extends Array<unknown> ? ElemType<X> : X>;
+    /**
+     * extract inner data from this query array and turn it into a QueryableArray of
+     * its own. Will automatically flatten data if the result of the key getter
+     * is an array.
+     *
+     * @param   keyGetter
+     *          The function through which to get the appropriate inner data
+     */
+    extract<X>(keyGetter: (t: T) => X): QueryableArray<X extends Array<unknown> ? ElemType<X> : X>;
+    joinWith<U>(them: U[]): {
+        /**
+         * a key on the current array that references a value in the provided
+         * array. This can be either a value or an array of values
+         *
+         * @param   myKeyGetter
+         *          A direct property name or function by which the referenceable
+         *          id(s) can be extracted via from an element in my array
+         *
+         * @returns A chainable joiner that can be used to set a new key to the
+         *          result of the join
+         **/
+        whereMy: <KT extends keyof T, X>(myKeyGetter: KT | ((t: T) => X)) => {
+            /**
+             * a key on the provided array that will have the same value as the
+             * result of retrieving the above key
+             *
+             * @param   theirKeyGetter
+             *          A direct property name or function by which the referenceable
+             *          id(s) can be extracted via from an element in their array
+             *
+             * @returns A chainable joiner that can be used to set a new key to the
+             *          result of the join
+             **/
+            referencesTheir: <KU extends keyof U, Y>(theirKeyGetter: KU | ((u: U) => Y)) => {
+                /**
+                 * what key on the original element the joined value / values
+                 * should be persisted to
+                 *
+                 * @param   joinKey
+                 *          A new or existing key for type T that the data that
+                 *          was joined will be added to
+                 *
+                 * @param   options
+                 *          Any additional tweaks to how this join should be
+                 *          performed.
+                 *
+                 * @returns A new QueryableArray with objects that contain the joined
+                 *          data
+                 **/
+                storedTo: <K extends string | number, TU extends T & { [k in K]?: T[KT] extends Array<unknown> ? U[] : U; } = T & { [k in K]?: T[KT] extends unknown[] ? U[] : U; }>(joinKey: K, { keepUndefinedReferences, }?: {
+                    /** if true, retains `undefined` as elements in a joined array
+                     * element being referenced couldn't be found */
+                    keepUndefinedReferences?: boolean;
+                }) => QueryableArray<TU>;
+            };
+        };
+    };
+    /**
+     * start filtering the array to elements that have a particular value for the
+     * specified property name.
+     *
+     * @param   propertyName
+     *          The property to extract from each element to perform further
+     *          queries on
+     *
+     * @returns A chainable QueryClause that can be resolved to filter the array
+     */
+    where<K extends keyof T, X extends T[K]>(propertyName: K): UnionToIntersection<QueryClause<X, QueryableArray<T>>>;
+    /**
+     * start filtering the array to elements that have a particualr value when
+     * passed through the specified extract function.
+     *
+     * @param   extractFn
+     *          The function to perform on each element in the array to get the
+     *          value that can have further queries performed on
+     *
+     * @returns A chainable QueryClause that can be resolved to filter the array
+     */
+    where<X>(extractFn: (t: T) => X): UnionToIntersection<QueryClause<X, QueryableArray<T>>>;
+    map<U>(fn: (t: T, idx: number, arr: T[]) => U): QueryableArray<U>;
+    filter(...args: Parameters<Array<T>["filter"]>): QueryableArray<T>;
+    concat(...args: Parameters<Array<T>["concat"]>): QueryableArray<T>;
+    slice(...args: Parameters<Array<T>["slice"]>): QueryableArray<T>;
+    flat<A, D extends number = 1>(depth?: D | undefined): QueryableArray<FlatArray<A, D>>;
+    flatMap<U>(callback: (value: T, index: number, array: T[]) => U | readonly U[]): QueryableArray<U>;
+    with(...args: Parameters<Array<T>["with"]>): QueryableArray<T>;
+    toSorted(...args: Parameters<Array<T>["toSorted"]>): QueryableArray<T>;
+    toReversed(): QueryableArray<T>;
+    toSpliced(startIdx: number, deleteCount?: number, replaceItem?: T): QueryableArray<T>;
+    fill(...args: Parameters<Array<T>["fill"]>): this;
+    sort(...args: Parameters<Array<T>["sort"]>): this;
+    reverse(): this;
+    splice(...args: Parameters<Array<T>["splice"]>): QueryableArray<T>;
+    copyWithin(target: number, start: number, end?: number): this;
+    includes(...args: Parameters<Array<T>["includes"]>): boolean;
+    find<U>(predicate: (value: T, index: number, obj: T[]) => U): T | undefined;
+    findIndex<U>(predicate: (value: T, index: number, obj: T[]) => U): number;
+    findLast<U>(predicate: (value: T, index: number, obj: T[]) => U): T | undefined;
+    findLastIndex<U>(predicate: (value: T, index: number, obj: T[]) => U): number;
+    indexOf(...args: Parameters<Array<T>["indexOf"]>): number;
+    lastIndexOf(...args: Parameters<Array<T>["lastIndexOf"]>): number;
+    forEach(...args: Parameters<Array<T>["forEach"]>): void;
+    every(predicate: (t: T) => boolean): boolean;
+    every<S extends T>(predicate: (t: T) => t is S): this is S[];
+    some(...args: Parameters<Array<T>["some"]>): boolean;
+    reduce<U = T, RT extends U extends Array<infer E> ? QueryableArray<E> : U = U extends Array<infer E> ? QueryableArray<E> : U>(callbackfn: (acc: U, cur: T, idx: number, arr: T[]) => U, initialValue?: U): RT;
+    reduceRight<U = T, RT extends U extends Array<infer E> ? QueryableArray<E> : U = U extends Array<infer E> ? QueryableArray<E> : U>(callbackfn: (acc: U, cur: T, idx: number, arr: T[]) => U, initialValue?: U): RT;
+    pop(): T | undefined;
+    shift(): T | undefined;
+    push(...args: Parameters<Array<T>["push"]>): number;
+    unshift(...args: Parameters<Array<T>["unshift"]>): number;
+    at(index: number): T | undefined;
+    entries(): ArrayIterator<[number, T]>;
+    values(): ArrayIterator<T>;
+    keys(): ArrayIterator<number>;
+    join(separator?: string): string;
+    toString(): string;
+    toLocaleString(): string;
+    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions & Intl.DateTimeFormatOptions): string;
+}
+
+export declare type QueryClause<T, R = QueryClauseResult<T>> = T extends Array<unknown> ? ArrayQueryClause<T, ElemType<T>, R> : T extends object ? ObjectQueryClause<T, R> : T extends string | number ? ComparableQueryClause<T, R> : BaseQueryClause<T, R>;
+
+export declare interface QueryClauseResult<T> {
+    isResolved: true;
+    result: boolean;
+}
+
+export declare enum SortOrder {
+    A_BEFORE_B = -1,
+    B_BEFORE_A = 1,
+    EQUAL = 0
+}
+
+export declare type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+export { }

package/dist/queryable-array.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var w=(e=>(e[e.A_BEFORE_B=-1]="A_BEFORE_B",e[e.B_BEFORE_A=1]="B_BEFORE_A",e[e.EQUAL=0]="EQUAL",e))(w||{});function v(e){return typeof e=="string"}function B(e){return typeof e=="number"}function L(e){return typeof e=="boolean"}function M(e){const t=typeof e;return t==="string"||t==="number"||t==="boolean"}function N(e){return typeof e=="symbol"}function d(e){return e instanceof Array}function X(e){return typeof e=="object"&&!d(e)&&e!==null}function E(e){return typeof e=="function"}function g(e){return typeof e=="object"&&e!==null}function R(e){return!(e===void 0||e===null)}function U(e,t="expected value to be true"){if(!e)throw new Error(t)}const q=e=>g(e)?Object.keys(e):[],m=(e,t)=>e===t?!0:M(e)||M(t)?!1:N(e)&&N(t)?e.toString()===t.toString():JSON.stringify(e)===JSON.stringify(t),A=(e,t)=>q(t).every(s=>g(t[s])&&g(e[s])?A(e[s],t[s]):m(e[s],t[s])),V=(e,t)=>!g(e)||!g(t)?m(e,t):[...q(e),...q(t)].every(s=>g(e[s])&&g(t[s])?V(e[s],t[s]):m(e[s],t[s])),F=Symbol("["),W=Symbol("]"),j=e=>{if(!R(e))return e;const t=[];for(const n of e){if(!d(n)){t.push(n);continue}t.push(F),n.forEach(s=>t.push(s)),t.push(W)}return t},Y=(e,t,n)=>{const s=[[]];let u=0,a=-1;if(e[0]!==F)return e.length>0&&e[t[0]](o=>n(o));for(let o=0;o<e.length;o+=1){const D=e[o];if(D===F){if(a>=0){a+=1;continue}u+=1,s[u]=[]}else if(D===W){if(a>0){a-=1;continue}a=-1;const p=t[u];if(!p)throw new Error("too few array logics passed");const h=s.pop(),c=h.length>0&&(p==="some"?h.some(r=>L(r)?r:n(r)):h.every(r=>L(r)?r:n(r)));u-=1,s[u].push(c);for(let r=u;r>=0;r-=1){const i=t[r];if(i==="some"&&c||i==="every"&&!c){if(r===0)return c;a+=1}else break}}else{if(a>=0)continue;s[u].push(D)}}U(s.length==1);const _=t[0],l=s[0];return l&&l.length>0&&(_==="some"?l.some(o=>o):l.every(o=>o))},Z=(e,t,n,s="and",u,a)=>{const _=(o,D=[],p=!1)=>{const h=r=>{const i=s==="and",J=(i?t:n).filter(O=>{if(!i&&u.has(O))return!0;const I=O?o(O):void 0,H=d(I)&&D.length>0;let T;H?T=Y(I,D,r):T=r(I);const x=p?!T:T;return x&&u.add(O),x});return a(J)},c={is:r=>g(r)?h(i=>m(i,r)):h(i=>r===i),eq:r=>c.is(r),equals:r=>c.is(r),isNull:()=>h(r=>r===null),isUndefined:()=>h(r=>r===void 0),isNullish:()=>h(r=>r==null),isEmpty:()=>h(r=>r instanceof Array?r.length===0:X(r)?Object.keys(r).length===0:!1),in:r=>h(i=>!!r.find(S=>S===i?!0:m(i,S))),satisfies:r=>h(r),greaterThan:r=>h(i=>B(i)||v(i)?i>r:!1),gt:r=>c.greaterThan(r),greaterThanOrEqualTo:r=>h(i=>B(i)||v(i)?i>=r:!1),gte:r=>c.greaterThanOrEqualTo(r),lessThan:r=>h(i=>B(i)||v(i)?i<r:!1),lt:r=>c.lessThan(r),lessThanOrEqualTo:r=>h(i=>B(i)||v(i)?i<=r:!1),lte:r=>c.lessThanOrEqualTo(r),matches:r=>h(i=>g(i)&&g(r)?A(i,r):!1),deepEquals:r=>h(i=>g(i)&&g(r)?V(i,r):!1),includes:r=>h(i=>d(i)?!!i.find(S=>m(r,S)):!1)};return c},l=(o,D=[],p=!1)=>({..._(o,D,p),get not(){return l(o,D,!p)},its:c=>l(r=>{const i=o(r);return d(i)&&D?i.map(S=>S?.[c]):i?.[c]},D,p),some:()=>l(c=>D.length==0?o(c):j(o(c)),[...D,"some"],p),every:()=>l(c=>D.length==0?o(c):j(o(c)),[...D,"every"],p)});return l(e)};class f extends Array{constructor(t,n,s="and",u=new Set){U(d(t)),super(t.length),this._currentLogic=s,this._currentSet=u,this._currentData=t,this._originalData=n??t.slice(0,t.length),this._populateInnerStore()}_currentData;_originalData;static get[Symbol.species](){return Array}get data(){return this._currentData}_populateInnerStore(){this.forEach((t,n)=>{const s=this._currentData[n];R(s)?this[n]=s:delete this[n]}),this.length=this._currentData.length}get first(){return this._currentData[0]}get last(){return this._currentData[this._currentData.length-1]}get and(){return this._currentLogic="and",this._currentSet=new Set,this}get or(){return this._currentLogic="or",this}unique(){return this.uniqueBy(t=>t)}uniqueBy(t){const n=s=>{const u={},a=[];return s.forEach(_=>{const l=E(t)?t(_):_[t],o=JSON.stringify(l);u[o]||(u[o]=!0,a.push(_))}),a};return new f(n(this._currentData),n(this._originalData),this._currentLogic,this._currentSet)}sortBy(t,n="asc"){const s=a=>E(t)?t(a):a[t],u=(a,_)=>{const l=s(a),o=s(_);return l<o?n==="asc"?w.A_BEFORE_B:w.B_BEFORE_A:l>o?n==="asc"?w.B_BEFORE_A:w.A_BEFORE_B:w.EQUAL};return new f([...this._currentData].sort(u),[...this._originalData].sort(u),this._currentLogic,this._currentSet)}indexBy(t){const n={},s=u=>E(t)?t(u):u?.[t];return this._currentData.forEach(u=>{n[s(u)]=u}),n}groupBy(t){const n={},s=u=>E(t)?t(u):u?.[t];return this._currentData.forEach(u=>{const a=s(u),_=d(a)?a:[a];for(const l of _)n[l]||(n[l]=[]),n[l].push(u)}),n}extract(t){return new f(this._currentData.flatMap(n=>E(t)?t(n):n[t]).filter(n=>!!n),this._originalData.flatMap(n=>E(t)?t(n):n[t]).filter(n=>!!n))}joinWith(t){return{whereMy:n=>{const s=E(n)?u=>n(u):u=>u[n];return{referencesTheir:u=>{const a=E(u)?_=>u(_):_=>_[u];return{storedTo:(_,{keepUndefinedReferences:l}={})=>{const o=D=>D.map(p=>{const h=s(p);if(d(h)){const c=h.map(r=>t.find(i=>a(i)===r));return{...p,[_]:l?c:c.filter(r=>!!r)}}else{const c=t.find(r=>a(r)===h);return{...p,[_]:c}}});return new f(o(this._currentData),o(this._originalData))}}}}}}}where(t){return Z(E(t)?n=>t(n):n=>n[t],this._currentData,this._originalData,this._currentLogic,this._currentSet,n=>new f(n,this._originalData,this._currentLogic,this._currentSet))}map(t){const n=this._currentData.map(t);return new f(n)}filter(...t){return new f(this._currentData.filter(...t),this._originalData,this._currentLogic,this._currentSet)}concat(...t){return new f(this._currentData.concat(...t))}slice(...t){return new f(this._currentData.slice(...t))}flat(t){return new f(this._currentData.flat(t))}flatMap(t){return new f(this._currentData.flatMap(t))}with(...t){return new f(this._currentData.with(...t))}toSorted(...t){return new f(this._currentData.toSorted(...t),this._originalData.toSorted(...t),this._currentLogic,this._currentSet)}toReversed(){return new f(this._currentData.toReversed(),this._originalData.toReversed(),this._currentLogic,this._currentSet)}toSpliced(t,n,s){return new f(R(n)&&R(s)?this._currentData.toSpliced(t,n,s):this._currentData.toSpliced(t,n),this._originalData,this._currentLogic,this._currentSet)}fill(...t){return this._currentData.fill(...t),this._populateInnerStore(),this}sort(...t){return this._currentData.sort(...t),this._populateInnerStore(),this._originalData.sort(...t),this}reverse(){return this._currentData.reverse(),this._populateInnerStore(),this._originalData.reverse(),this}splice(...t){const n=this._currentData.splice(...t);return this._populateInnerStore(),new f(n)}copyWithin(t,n,s){return this._currentData.copyWithin(t,n,s),this._populateInnerStore(),this}includes(...t){return this._currentData.includes(...t)}find(t){return this._currentData.find(t)}findIndex(t){return this._currentData.findIndex(t)}findLast(t){return this._currentData.findLast(t)}findLastIndex(t){return this._currentData.findLastIndex(t)}indexOf(...t){return this._currentData.indexOf(...t)}lastIndexOf(...t){return this._currentData.lastIndexOf(...t)}forEach(...t){return this._currentData.forEach(...t)}every(t){return this._currentData.every(t)}some(...t){return this._currentData.some(...t)}reduce(t,n){const s=this._currentData.reduce(t,n);return d(s)?new f(s):s}reduceRight(t,n){const s=this._currentData.reduceRight(t,n);return d(s)?new f(s):s}pop(){const t=this._currentData.pop();return this._populateInnerStore(),t}shift(){const t=this._currentData.shift();return this._populateInnerStore(),t}push(...t){const n=this._currentData.push(...t);return this._populateInnerStore(),n}unshift(...t){const n=this._currentData.unshift(...t);return this._populateInnerStore(),n}at(t){return this._currentData.at(t)}entries(){return this._currentData.entries()}values(){return this._currentData.values()}keys(){return this._currentData.keys()}join(t){return this._currentData.join(t)}toString(){return this._currentData.toString()}toLocaleString(t,n){return t?this._currentData.toLocaleString(t,n):this._currentData.toLocaleString()}}function P(e){return d(e)?new f(e):new f([e],[e])}const $=P;exports.ql=$;exports.queryable=P;

package/dist/queryable-array.mjs

@@ -0,0 +1,626 @@
+var w = /* @__PURE__ */ ((e) => (e[e.A_BEFORE_B = -1] = "A_BEFORE_B", e[e.B_BEFORE_A = 1] = "B_BEFORE_A", e[e.EQUAL = 0] = "EQUAL", e))(w || {});
+function R(e) {
+  return typeof e == "string";
+}
+function T(e) {
+  return typeof e == "number";
+}
+function L(e) {
+  return typeof e == "boolean";
+}
+function M(e) {
+  const t = typeof e;
+  return t === "string" || t === "number" || t === "boolean";
+}
+function N(e) {
+  return typeof e == "symbol";
+}
+function d(e) {
+  return e instanceof Array;
+}
+function H(e) {
+  return typeof e == "object" && !d(e) && e !== null;
+}
+function E(e) {
+  return typeof e == "function";
+}
+function g(e) {
+  return typeof e == "object" && e !== null;
+}
+function v(e) {
+  return !(e === void 0 || e === null);
+}
+function U(e, t = "expected value to be true") {
+  if (!e)
+    throw new Error(t);
+}
+const F = (e) => g(e) ? Object.keys(e) : [], m = (e, t) => e === t ? !0 : M(e) || M(t) ? !1 : N(e) && N(t) ? e.toString() === t.toString() : JSON.stringify(e) === JSON.stringify(t), A = (e, t) => F(t).every((s) => g(t[s]) && g(e[s]) ? A(e[s], t[s]) : m(e[s], t[s])), V = (e, t) => !g(e) || !g(t) ? m(e, t) : [...F(e), ...F(t)].every((s) => g(e[s]) && g(t[s]) ? V(e[s], t[s]) : m(e[s], t[s])), x = /* @__PURE__ */ Symbol("["), W = /* @__PURE__ */ Symbol("]"), j = (e) => {
+  if (!v(e))
+    return e;
+  const t = [];
+  for (const n of e) {
+    if (!d(n)) {
+      t.push(n);
+      continue;
+    }
+    t.push(x), n.forEach((s) => t.push(s)), t.push(W);
+  }
+  return t;
+}, X = (e, t, n) => {
+  const s = [[]];
+  let u = 0, a = -1;
+  if (e[0] !== x)
+    return e.length > 0 && e[t[0]]((o) => n(o));
+  for (let o = 0; o < e.length; o += 1) {
+    const D = e[o];
+    if (D === x) {
+      if (a >= 0) {
+        a += 1;
+        continue;
+      }
+      u += 1, s[u] = [];
+    } else if (D === W) {
+      if (a > 0) {
+        a -= 1;
+        continue;
+      }
+      a = -1;
+      const p = t[u];
+      if (!p)
+        throw new Error("too few array logics passed");
+      const h = s.pop(), c = h.length > 0 && (p === "some" ? h.some((r) => L(r) ? r : n(r)) : h.every((r) => L(r) ? r : n(r)));
+      u -= 1, s[u].push(c);
+      for (let r = u; r >= 0; r -= 1) {
+        const i = t[r];
+        if (
+          // any true value will succeed in a 'some' evaluation
+          i === "some" && c || // any false value will fail in an 'every' evaluation
+          i === "every" && !c
+        ) {
+          if (r === 0)
+            return c;
+          a += 1;
+        } else
+          break;
+      }
+    } else {
+      if (a >= 0)
+        continue;
+      s[u].push(D);
+    }
+  }
+  U(s.length == 1);
+  const _ = t[0], l = s[0];
+  return l && l.length > 0 && (_ === "some" ? l.some((o) => o) : l.every((o) => o));
+}, Y = (e, t, n, s = "and", u, a) => {
+  const _ = (o, D = [], p = !1) => {
+    const h = (r) => {
+      const i = s === "and", J = (i ? t : n).filter((B) => {
+        if (!i && u.has(B))
+          return !0;
+        const I = B ? o(B) : void 0, P = d(I) && D.length > 0;
+        let O;
+        P ? O = X(
+          I,
+          D,
+          r
+        ) : O = r(I);
+        const q = p ? !O : O;
+        return q && u.add(B), q;
+      });
+      return a(J);
+    }, c = {
+      is: (r) => g(r) ? h((i) => m(i, r)) : h((i) => r === i),
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      eq: (r) => c.is(r),
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      equals: (r) => c.is(r),
+      isNull: () => h((r) => r === null),
+      isUndefined: () => h((r) => r === void 0),
+      isNullish: () => h((r) => r == null),
+      isEmpty: () => h(
+        (r) => r instanceof Array ? r.length === 0 : H(r) ? Object.keys(r).length === 0 : !1
+      ),
+      in: (r) => h((i) => !!r.find((S) => S === i ? !0 : m(i, S))),
+      satisfies: (r) => h(r),
+      greaterThan: (r) => h((i) => T(i) || R(i) ? i > r : !1),
+      gt: (r) => c.greaterThan(
+        r
+      ),
+      greaterThanOrEqualTo: (r) => h((i) => T(i) || R(i) ? i >= r : !1),
+      gte: (r) => c.greaterThanOrEqualTo(r),
+      lessThan: (r) => h((i) => T(i) || R(i) ? i < r : !1),
+      lt: (r) => c.lessThan(
+        r
+      ),
+      lessThanOrEqualTo: (r) => h((i) => T(i) || R(i) ? i <= r : !1),
+      lte: (r) => c.lessThanOrEqualTo(r),
+      matches: (r) => h((i) => g(i) && g(r) ? A(i, r) : !1),
+      deepEquals: (r) => h((i) => g(i) && g(r) ? V(i, r) : !1),
+      includes: (r) => h((i) => d(i) ? !!i.find((S) => m(r, S)) : !1)
+    };
+    return c;
+  }, l = (o, D = [], p = !1) => ({
+    ..._(o, D, p),
+    get not() {
+      return l(o, D, !p);
+    },
+    its: (c) => l(
+      (r) => {
+        const i = o(r);
+        return d(i) && D ? i.map((S) => S?.[c]) : i?.[c];
+      },
+      D,
+      p
+    ),
+    some: () => l(
+      (c) => D.length == 0 ? o(c) : j(o(c)),
+      [...D, "some"],
+      p
+    ),
+    every: () => l(
+      (c) => D.length == 0 ? o(c) : j(o(c)),
+      [...D, "every"],
+      p
+    )
+  });
+  return l(e);
+};
+class f extends Array {
+  constructor(t, n, s = "and", u = /* @__PURE__ */ new Set()) {
+    U(d(t)), super(t.length), this._currentLogic = s, this._currentSet = u, this._currentData = t, this._originalData = n ?? t.slice(0, t.length), this._populateInnerStore();
+  }
+  _currentData;
+  _originalData;
+  /** ensure that we instantiate intermediate versions of query arrays (e.g.
+   * through .filter or .map) as a straight array instance -- we will always
+   * explicitly wrap the result in a QueryableArray when appropriate */
+  static get [Symbol.species]() {
+    return Array;
+  }
+  get data() {
+    return this._currentData;
+  }
+  /**
+   * ensure that we have the elements from _currentData also populated into our
+   * numeric indices, so that you can extract data as you would from a regular
+   * array
+   **/
+  _populateInnerStore() {
+    this.forEach((t, n) => {
+      const s = this._currentData[n];
+      v(s) ? this[n] = s : delete this[n];
+    }), this.length = this._currentData.length;
+  }
+  /**
+   * get the first element in the query array, based on the current query
+   */
+  get first() {
+    return this._currentData[0];
+  }
+  /**
+   * get the last element in the query array, based on the current query
+   */
+  get last() {
+    return this._currentData[this._currentData.length - 1];
+  }
+  /**
+   * apply a new query to the array, enusring that only elements that match
+   * both the current query and the new query are included
+   */
+  get and() {
+    return this._currentLogic = "and", this._currentSet = /* @__PURE__ */ new Set(), this;
+  }
+  /**
+   * apply a new query to the array, ensuring that elements that match either
+   * the current query or the new query are included (without duplicates)
+   */
+  get or() {
+    return this._currentLogic = "or", this;
+  }
+  /**
+   * Remove any duplicate members of the array, via deep-equality comparison
+   *
+   * @returns This QueryableArray sans duplicate members
+   */
+  unique() {
+    return this.uniqueBy((t) => t);
+  }
+  /**
+   * Remove any members of the array that are considered a duplicate via the
+   * provided key getter.
+   *
+   * @param   keyGetter
+   *          Either a property name or a function that can be used to get the
+   *          value that should be compared for uniqueness
+   *
+   * @returns This QueryableArray sans duplicate members
+   */
+  uniqueBy(t) {
+    const n = (s) => {
+      const u = {}, a = [];
+      return s.forEach((_) => {
+        const l = E(t) ? t(_) : _[t], o = JSON.stringify(l);
+        u[o] || (u[o] = !0, a.push(_));
+      }), a;
+    };
+    return new f(
+      n(this._currentData),
+      n(this._originalData),
+      this._currentLogic,
+      this._currentSet
+    );
+  }
+  /**
+   * sort the query array by either the value in the specified property or via
+   * a function evaluator.
+   *
+   * @param   sortKeyGetter
+   *          The property or function that can retrieve a sortable value from
+   *          a given element
+   *
+   * @param   direction
+   *          Whether we should perform an ascending or descending search
+   *
+   * @returns A sorted version of this query array
+   */
+  sortBy(t, n = "asc") {
+    const s = (a) => E(t) ? t(a) : a[t], u = (a, _) => {
+      const l = s(a), o = s(_);
+      return l < o ? n === "asc" ? w.A_BEFORE_B : w.B_BEFORE_A : l > o ? n === "asc" ? w.B_BEFORE_A : w.A_BEFORE_B : w.EQUAL;
+    };
+    return new f(
+      [...this._currentData].sort(u),
+      [...this._originalData].sort(u),
+      this._currentLogic,
+      this._currentSet
+    );
+  }
+  /**
+   * turn this query array into a map, with keys based on the provided key
+   * getter.
+   *
+   * This assumes that the key retrieved is unique for the element in
+   * question; if multiple elements could return the same key, use `groupBy`
+   * instead
+   *
+   * @param   keyGetter
+   *          A function or name of a property that can extract an appropriate
+   *          key for any given element.
+   *
+   * @returns A map of the query array, keyed by the results of the keyGetter
+   */
+  indexBy(t) {
+    const n = {}, s = (u) => E(t) ? t(u) : u?.[t];
+    return this._currentData.forEach((u) => {
+      n[s(u)] = u;
+    }), n;
+  }
+  /**
+   * group all elements in the query array by a given key
+   *
+   * @param   keyGetter
+   *          The property name or function to retrieve the value
+   *
+   * @returns A map with keys based on the results of keyGetter and an array
+   *          of values that returned that key
+   */
+  groupBy(t) {
+    const n = {}, s = (u) => E(t) ? t(u) : u?.[t];
+    return this._currentData.forEach((u) => {
+      const a = s(u), _ = d(a) ? a : [a];
+      for (const l of _)
+        n[l] || (n[l] = []), n[l].push(u);
+    }), n;
+  }
+  /**
+   * extract inner data from this query array and turn it into a QueryableArray of
+   * its own. Will automatically flatten data if the result of the key getter
+   * is an array.
+   */
+  extract(t) {
+    return new f(
+      this._currentData.flatMap(
+        (n) => E(t) ? t(n) : n[t]
+      ).filter((n) => !!n),
+      this._originalData.flatMap(
+        (n) => E(t) ? t(n) : n[t]
+      ).filter((n) => !!n)
+    );
+  }
+  joinWith(t) {
+    return {
+      /**
+       * a key on the current array that references a value in the provided
+       * array. This can be either a value or an array of values
+       *
+       * @param   myKeyGetter
+       *          A direct property name or function by which the referenceable
+       *          id(s) can be extracted via from an element in my array
+       *
+       * @returns A chainable joiner that can be used to set a new key to the
+       *          result of the join
+       **/
+      whereMy: (n) => {
+        const s = E(n) ? (u) => n(u) : (u) => u[n];
+        return {
+          /**
+           * a key on the provided array that will have the same value as the
+           * result of retrieving the above key
+           *
+           * @param   theirKeyGetter
+           *          A direct property name or function by which the referenceable
+           *          id(s) can be extracted via from an element in their array
+           *
+           * @returns A chainable joiner that can be used to set a new key to the
+           *          result of the join
+           **/
+          referencesTheir: (u) => {
+            const a = E(u) ? (_) => u(_) : (_) => _[u];
+            return {
+              /**
+               * what key on the original element the joined value / values
+               * should be persisted to
+               *
+               * @param   joinKey
+               *          A new or existing key for type T that the data that
+               *          was joined will be added to
+               *
+               * @param   options
+               *          Any additional tweaks to how this join should be
+               *          performed.
+               *
+               * @returns A new QueryableArray with objects that contain the joined
+               *          data
+               **/
+              storedTo: (_, {
+                keepUndefinedReferences: l
+              } = {}) => {
+                const o = (D) => D.map((p) => {
+                  const h = s(p);
+                  if (d(h)) {
+                    const c = h.map(
+                      (r) => t.find((i) => a(i) === r)
+                    );
+                    return {
+                      ...p,
+                      [_]: l ? c : c.filter((r) => !!r)
+                    };
+                  } else {
+                    const c = t.find(
+                      (r) => a(r) === h
+                    );
+                    return {
+                      ...p,
+                      [_]: c
+                    };
+                  }
+                });
+                return new f(
+                  o(this._currentData),
+                  o(this._originalData)
+                );
+              }
+            };
+          }
+        };
+      }
+    };
+  }
+  /**
+   * perform a where query either on a caller-specified getter or via a set of
+   * query clauses that have already been queued up for our use by a previous
+   * iteration of the query array
+   *
+   * @param   keyOrFn
+   *          The method through which we should retrieve values for this query
+   *          array. Ignored if `myQueryClauses` is set.
+   *
+   * @param   myQueryClauses
+   *          If available, previous iterations of running this query arrays
+   *          values through a value extraction, then passed on to a query
+   *          clause. Largely used in cases when we are working with deeply
+   *          nested arrays or objects, as they have special handling built
+   *          into the query clause object to resolve deeply with type safety
+   *
+   * @returns A new QueryClause that can be resolved to filter the query array
+   *          down based on further chained function calls.
+   */
+  where(t) {
+    return Y(
+      E(t) ? (n) => t(n) : (n) => n[t],
+      this._currentData,
+      this._originalData,
+      this._currentLogic,
+      this._currentSet,
+      (n) => new f(
+        n,
+        this._originalData,
+        this._currentLogic,
+        this._currentSet
+      )
+    );
+  }
+  // =========================================
+  // OVERRIDDEN ARRAY METHODS RETURNING ARRAYS
+  // =========================================
+  // These are methods that in a native array, will return another array.
+  // These will be wrapped in a QueryableArray instead, after being performed on
+  // the native _currentData array
+  map(t) {
+    const n = this._currentData.map(t);
+    return new f(n);
+  }
+  filter(...t) {
+    return new f(
+      this._currentData.filter(...t),
+      this._originalData,
+      this._currentLogic,
+      this._currentSet
+    );
+  }
+  concat(...t) {
+    return new f(this._currentData.concat(...t));
+  }
+  slice(...t) {
+    return new f(this._currentData.slice(...t));
+  }
+  flat(t) {
+    return new f(
+      this._currentData.flat(t)
+    );
+  }
+  flatMap(t) {
+    return new f(this._currentData.flatMap(t));
+  }
+  with(...t) {
+    return new f(this._currentData.with(...t));
+  }
+  toSorted(...t) {
+    return new f(
+      this._currentData.toSorted(...t),
+      this._originalData.toSorted(...t),
+      this._currentLogic,
+      this._currentSet
+    );
+  }
+  toReversed() {
+    return new f(
+      this._currentData.toReversed(),
+      this._originalData.toReversed(),
+      this._currentLogic,
+      this._currentSet
+    );
+  }
+  toSpliced(t, n, s) {
+    return new f(
+      v(n) && v(s) ? this._currentData.toSpliced(t, n, s) : this._currentData.toSpliced(t, n),
+      this._originalData,
+      this._currentLogic,
+      this._currentSet
+    );
+  }
+  // ===========================================
+  // OVERRIDDEN IN-PLACE MODIFYING ARRAY METHODS
+  // ===========================================
+  // These are methods that operate directly on the current array reference
+  // rather than returning a new copy of the array with the operation performed.
+  // We perform these methods on the native _currentData array, then update
+  // our inner store to reflect the updates to the _currentData array before
+  // returning an appropriate result for the method.
+  fill(...t) {
+    return this._currentData.fill(...t), this._populateInnerStore(), this;
+  }
+  sort(...t) {
+    return this._currentData.sort(...t), this._populateInnerStore(), this._originalData.sort(...t), this;
+  }
+  reverse() {
+    return this._currentData.reverse(), this._populateInnerStore(), this._originalData.reverse(), this;
+  }
+  splice(...t) {
+    const n = this._currentData.splice(...t);
+    return this._populateInnerStore(), new f(n);
+  }
+  copyWithin(t, n, s) {
+    return this._currentData.copyWithin(t, n, s), this._populateInnerStore(), this;
+  }
+  // =========================================
+  // OVERRIDDEN ARRAY METHODS FOR OPTIMIZATION
+  // =========================================
+  // These are methods that we anticipate being slower when run directly on a
+  // QueryableArray, as a result of the optimization that our semi-custom
+  // implementation requires. These pass through the function call to our
+  // _currentData array to take advantage of the optimized versions
+  includes(...t) {
+    return this._currentData.includes(...t);
+  }
+  find(t) {
+    return this._currentData.find(t);
+  }
+  findIndex(t) {
+    return this._currentData.findIndex(t);
+  }
+  findLast(t) {
+    return this._currentData.findLast(t);
+  }
+  findLastIndex(t) {
+    return this._currentData.findLastIndex(t);
+  }
+  indexOf(...t) {
+    return this._currentData.indexOf(...t);
+  }
+  lastIndexOf(...t) {
+    return this._currentData.lastIndexOf(...t);
+  }
+  forEach(...t) {
+    return this._currentData.forEach(...t);
+  }
+  every(t) {
+    return this._currentData.every(t);
+  }
+  some(...t) {
+    return this._currentData.some(...t);
+  }
+  reduce(t, n) {
+    const s = this._currentData.reduce(t, n);
+    return d(s) ? new f(s) : s;
+  }
+  reduceRight(t, n) {
+    const s = this._currentData.reduceRight(t, n);
+    return d(s) ? new f(s) : s;
+  }
+  // ==========================================
+  // OVERRIDDEN ARRAY METHODS FOR FUNCTIONALITY
+  // ==========================================
+  // These are methods that, if we didn't override them within our instance, we
+  // would end up with odd behavior as the interior array and the external
+  // representation of it would no longer match.
+  pop() {
+    const t = this._currentData.pop();
+    return this._populateInnerStore(), t;
+  }
+  shift() {
+    const t = this._currentData.shift();
+    return this._populateInnerStore(), t;
+  }
+  push(...t) {
+    const n = this._currentData.push(...t);
+    return this._populateInnerStore(), n;
+  }
+  unshift(...t) {
+    const n = this._currentData.unshift(...t);
+    return this._populateInnerStore(), n;
+  }
+  at(t) {
+    return this._currentData.at(t);
+  }
+  entries() {
+    return this._currentData.entries();
+  }
+  values() {
+    return this._currentData.values();
+  }
+  keys() {
+    return this._currentData.keys();
+  }
+  join(t) {
+    return this._currentData.join(t);
+  }
+  toString() {
+    return this._currentData.toString();
+  }
+  toLocaleString(t, n) {
+    return t ? this._currentData.toLocaleString(t, n) : this._currentData.toLocaleString();
+  }
+}
+function Z(e) {
+  return d(e) ? new f(e) : new f(
+    [e],
+    [e]
+  );
+}
+const $ = Z;
+export {
+  $ as ql,
+  Z as queryable
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "queryable-array",
+  "version": "1.0.0",
+  "description": "",
+  "type": "module",
+  "main": "./dist/queryable-array.cjs",
+  "module": "./dist/queryable-array.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/queryable-array.mjs",
+      "require": "./dist/queryable-array.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest",
+    "test:benchmark": "vitest bench",
+    "test:benchmark:report": "vitest bench --outputJson benchmark.json --watch false && node scripts/benchmarkFormatter.js && rm benchmark.json",
+    "lint": "eslint"
+  },
+  "keywords": [
+    "query",
+    "filter"
+  ],
+  "author": "Kip Price",
+  "homepage": "https://practically.cool",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kipprice/queryable-array.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kipprice/queryable-array/issues"
+  },
+  "packageManager": "pnpm@10.17.1",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.2.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.2",
+    "globals": "^17.4.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.18"
+  }
+}