flat-pair 1.0.1 → 1.2.0

package/README.md

@@ -14,8 +14,9 @@ For more awesome packages, check out [my homepage💛](https://baendlorel.github
 - 🛡️ **Type Safe**: Full TypeScript support with generic types
 - 🎯 **Zero Cost**: Static methods available for minimal overhead
 - ⚡ **Lightweight**: No dependencies, minimal bundle size
+- 🌲 **Native Behavior**: `forEach`, `find` acts like they are in `Array`. Equality check uses `SameValueZero`
 
-## Installation
+## Installation / Import
 
 ```bash
 npm install flat-pair
@@ -23,98 +24,33 @@ npm install flat-pair
 pnpm install flat-pair
 ```
 
-## Quick Start
-
-### Using the FlatPair Class
-
 ```typescript
-import { FlatPair } from 'flat-pair';
-
-// Create from Map
-const map = new Map([
-  ['name', 'John'],
-  ['age', 25],
-]);
-const flatPair = FlatPair.from(map);
-
-// Or create directly
-const pair = new FlatPair(['name', 'John', 'age', 25]);
-
-// Add key-value pairs (won't add duplicates)
-pair.add('city', 'New York');
-pair.add('name', 'Jane'); // Won't override existing key
-
-// Find by key
-console.log(pair.find('name')); // 'John'
-
-// Find by value
-console.log(pair.findByValue('New York')); // 'city'
-
-// Remove pairs
-pair.remove('age'); // returns true
-pair.remove('nonexistent'); // returns false
-
-// Get size
-console.log(pair.size); // 2
-
-// Clear all
-pair.clear();
+import { FlatPair, FlatPairOperator, add, get, find ...others } from 'flat-pair';
 ```
 
-### Iteration and at()
-
-FlatPair implements iterator helpers similar to `Map` and arrays:
-
-- `forEach()` - like normal `forEach` from Array
-- `keys()` - returns an iterator over keys
-- `values()` - returns an iterator over values
-- `entries()` - returns an iterator over [key, value] pairs
-- `Symbol.iterator` - the default iterator, same as `entries()`
-- `at(index)` - returns the [key, value] pair at zero-based index or `undefined` if out of range
-
-```typescript
-// keys / values / entries
-console.log([...fp.keys()]); // ['a','b']
-console.log([...fp.values()]); // [1,2]
-console.log([...fp.entries()]); // [['a',1], ['b',2]]
-
-// default iterator
-for (const [k, v] of fp) {
-  console.log(k, v);
-}
-
-// at
-console.log(fp.at(0)); // ['a', 1]
-console.log(fp.at(2)); // undefined
-```
+## Quick Start
 
-### forEach
+### FlatPair Class
 
-`forEach` iterates pairs and follows the callback signature `(value, key, index, arr)` and accepts an optional `thisArg`.
+`FlatPair` is a container class has an `items` array, it has methods that wrap the static functions for easier usage.
 
 ```typescript
-fp.forEach(
-  function (value, key, index, arr) {
-    console.log(index, key, value, arr === (fp as any).items);
-  },
-  { myThis: true }
-);
+// userId - detail pair
+const pairs = new FlatPair<number, Detail>();
+pairs.add(1, { name: 'Alice', age: 30 });
+pairs.add(2, { name: 'Bob', age: 25 });
+pairs.remove(1);
+pairs.find((value, key) => value.age > 20);
 ```
 
 ### Using Static Functions (Zero Cost)
 
 ```typescript
-import { add, find, findByValue, remove, size, clear } from 'flat-pair';
-
 const items: any[] = [];
 
 // Add items
-add(items, 'name', 'John');
-add(items, 'age', 25);
-
-// Find operations
-const name = find(items, 'name'); // 'John'
-const ageKey = findByValue(items, 25); // 'age'
+add<string, string>(items, 'name', 'John');
+add<string, number>(items, 'age', 12);
 
 // Remove and other operations
 remove(items, 'age'); // returns true
@@ -124,17 +60,19 @@ clear(items); // empties the array
 
 ### Using FlatPairOperator Class (For fixed type hint)
 
+If you don't want to specify the generic types every time you call a static function, you can use `FlatPairOperator` which wraps the static functions with fixed generic types.
+
 ```typescript
 import { FlatPairOperator } from 'flat-pair';
 
 const operator = new FlatPairOperator<string, number>();
 const items: any[] = [];
 
-operator.add(items, 'score', 100);
+operator.add(items, 'score', 100); // operator's add method is always typed
 operator.add(items, 'level', 5);
 
-console.log(operator.find(items, 'score')); // 100
-console.log(operator.findByValue(items, 5)); // 'level'
+console.log(operator.get(items, 'score')); // 100
+console.log(operator.getByValue(items, 5)); // 'level'
 ```
 
 ## Performance

package/dist/index.d.ts

@@ -1,19 +1,27 @@
 declare class FlatPair<K, V> {
     static from<T extends Map<any, any>>(map: T): T extends Map<infer K, infer V> ? FlatPair<K, V> : never;
-    private readonly items;
+    private readonly _items;
     constructor(items: any[]);
     get size(): number;
+    /**
+     * A reference to the internal array
+     * - associated with `this.findIndex`
+     */
+    get array(): any[];
     /**
      * Will check if the key already exists, if so then do nothing.
      */
     add(key: K, value: V): this;
+    hasByValue(value: V): boolean;
     remove(key: K): boolean;
     removeByValue(value: V): boolean;
-    find(key: K): V | undefined;
-    findByValue(value: V): K | undefined;
-    at(pairIndex: number): [K, V] | undefined;
+    get(key: K): V | undefined;
+    getByValue(value: V): K | undefined;
+    find(predicate: (value: V, key: K, index: number, array: any[]) => boolean): [K, V] | undefined;
+    findIndex(predicate: (value: V, key: K, index: number, array: any[]) => boolean): number;
     clear(): void;
-    forEach(callback: (value: V, key: K, pairIndex: number, array: any[]) => void, thisArg?: any): void;
+    has(key: K): boolean;
+    forEach(callback: (value: V, key: K, index: number, array: any[]) => void, thisArg?: any): void;
     keys(): IterableIterator<K>;
     values(): IterableIterator<V>;
     entries(): IterableIterator<[K, V]>;
@@ -26,30 +34,36 @@ declare class FlatPair<K, V> {
 declare class FlatPairOperator<K, V> {
     add(items: any[], key: K, value: V): void;
     remove(items: any[], key: K): boolean;
-    find(items: any[], key: K): V | undefined;
-    findByValue(items: any[], value: V): K | undefined;
+    get(items: any[], key: K): V | undefined;
+    getByValue(items: any[], value: V): K | undefined;
+    find(items: any[], predicate: (value: V, key: K, index: number, array: any[]) => boolean): [K, V] | undefined;
+    findIndex(items: any[], predicate: (value: V, key: K, index: number, array: any[]) => boolean): number;
     removeByValue(items: any[], value: V): boolean;
-    forEach(items: any[], callback: (value: V, key: K, pairIndex: number, array: any[]) => void, thisArg?: any): void;
-    at(items: any[], pairIndex: number): [K, V] | undefined;
+    forEach(items: any[], callback: (value: V, key: K, index: number, array: any[]) => void, thisArg?: any): void;
     keys(items: any[]): IterableIterator<K>;
     values(items: any[]): IterableIterator<V>;
     entries(items: any[]): IterableIterator<[K, V]>;
     clear(items: any[]): void;
+    has(items: any[], key: K): boolean;
+    hasByValue(items: any[], value: V): boolean;
 }
 
-declare function add<K, V>(items: any[], key: K, value: V): void;
 declare function size(items: any[]): number;
-declare function find<K, V>(items: any[], key: K): V | undefined;
-declare function findByValue<K, V>(items: any[], value: V): K | undefined;
+declare function add<K, V>(items: any[], key: K, value: V): void;
+declare function has<K>(items: any[], key: K): boolean;
+declare function hasByValue<V>(items: any[], value: V): boolean;
+declare function get<K, V>(items: any[], key: K): V | undefined;
+declare function getByValue<K, V>(items: any[], value: V): K | undefined;
 declare function remove<K>(items: any[], key: K): boolean;
 declare function removeByValue<V>(items: any[], value: V): boolean;
 /**
  * Behaviors are similar to `Array.prototype.forEach`, caches length and checks index existence.
  *
- * - `callback`: real index in the `arr` is `2 * pairIndex`.
+ * - `callback`: index is the index of array, not the pair count.
  */
-declare function forEach<K, V>(items: any[], callback: (value: V, key: K, pairIndex: number, array: any[]) => void, thisArg?: any): void;
-declare function at<K, V>(items: any[], pairIndex: number): [K, V] | undefined;
+declare function forEach<K, V>(items: any[], callback: (value: V, key: K, index: number, array: any[]) => void, thisArg?: any): void;
 declare function clear(items: any[]): void;
+declare function find<K, V>(items: any[], predicate: (value: V, key: K, index: number, array: any[]) => boolean): [K, V] | undefined;
+declare function findIndex<K, V>(items: any[], predicate: (value: V, key: K, index: number, array: any[]) => boolean): number;
 
-export { FlatPair, FlatPairOperator, add, at, clear, find, findByValue, forEach, remove, removeByValue, size };
+export { FlatPair, FlatPairOperator, add, clear, find, findIndex, forEach, get, getByValue, has, hasByValue, remove, removeByValue, size };

package/dist/index.mjs

@@ -1 +1 @@
-function t(t,e,r){const n=t.length;for(let r=0;r<n;r+=2)if(t[r]===e)return;t.push(e,r)}function e(t){const e=t.length;if(e%2!=0)throw new Error("Invalid items length, must be even number");return e/2}function r(t,e){const r=t.length;for(let n=0;n<r;n+=2)if(t[n]===e)return t[n+1]}function n(t,e){const r=t.length;for(let n=1;n<r;n+=2)if(t[n]===e)return t[n-1]}function i(t,e){const r=t.length;for(let n=0;n<r;n+=2)if(t[n]===e)return t.splice(n,2),!0;return!1}function o(t,e){const r=t.length;for(let n=1;n<r;n+=2)if(t[n]===e)return t.splice(n-1,2),!0;return!1}function s(t,e,r){let n=0;const i=t.length;for(let o=0;o<i;o+=2)o in t&&e.call(r,t[o+1],t[o],n,t),n++}function u(t,e){if(e<0)return;const r=2*e;return r+1>=t.length?void 0:[t[r],t[r+1]]}function f(t){t.length=0}class l{static from(t){if("[object Map]"!==Object.prototype.toString.call(t))throw new TypeError("[FlatPair: __func__] Argument must be a Map");const e=[];return t.forEach((t,r)=>e.push(r,t)),new l(e)}items=[];constructor(t){if(t.length%2!=0)throw new TypeError("FlatPair items length must be even");this.items=t}get size(){return this.items.length/2}add(e,r){return t(this.items,e,r),this}remove(t){return i(this.items,t)}removeByValue(t){return o(this.items,t)}find(t){return r(this.items,t)}findByValue(t){return n(this.items,t)}at(t){return u(this.items,t)}clear(){this.items.length=0}forEach(t,e){s(this.items,t,e)}*keys(){for(let t=0;t<this.items.length;t+=2)yield this.items[t]}*values(){for(let t=1;t<this.items.length;t+=2)yield this.items[t]}*entries(){for(let t=0;t<this.items.length;t+=2)yield[this.items[t],this.items[t+1]]}[Symbol.iterator](){return this.entries()}}class c{add(e,r,n){t(e,r,n)}remove(t,e){return i(t,e)}find(t,e){return r(t,e)}findByValue(t,e){return n(t,e)}removeByValue(t,e){return o(t,e)}forEach(t,e,r){s(t,e,r)}at(t,e){return u(t,e)}*keys(t){for(let e=0;e<t.length;e+=2)yield t[e]}*values(t){for(let e=1;e<t.length;e+=2)yield t[e]}*entries(t){for(let e=0;e<t.length;e+=2)yield[t[e],t[e+1]]}clear(t){t.length=0}}export{l as FlatPair,c as FlatPairOperator,t as add,u as at,f as clear,r as find,n as findByValue,s as forEach,i as remove,o as removeByValue,e as size};
+const e=function(e,r){return e===r||e!=e&&r!=r};function r(e){const r=e.length;if(r%2!=0)throw new TypeError("[FlatPair: size] items length must be even number");return r/2}function t(r,t,n){const i=r.length;if(i%2!=0)throw new TypeError("[FlatPair: add] items length must be even number");for(let n=0;n<i;n+=2)if(e(r[n],t))return;r.push(t,n)}function n(r,t){const n=r.length;if(n%2!=0)throw new TypeError("[FlatPair: has] items length must be even number");for(let i=0;i<n;i+=2)if(e(r[i],t))return!0;return!1}function i(r,t){const n=r.length;if(n%2!=0)throw new TypeError("[FlatPair: hasByValue] items length must be even number");for(let i=1;i<n;i+=2)if(e(r[i],t))return!0;return!1}function u(r,t){const n=r.length;if(n%2!=0)throw new TypeError("[FlatPair: get] items length must be even number");for(let i=0;i<n;i+=2)if(e(r[i],t))return r[i+1]}function o(r,t){const n=r.length;if(n%2!=0)throw new TypeError("[FlatPair: getByValue] items length must be even number");for(let i=1;i<n;i+=2)if(e(r[i],t))return r[i-1]}function s(r,t){const n=r.length;if(n%2!=0)throw new TypeError("[FlatPair: remove] items length must be even number");for(let i=0;i<n;i+=2)if(e(r[i],t))return r.splice(i,2),!0;return!1}function l(r,t){const n=r.length;if(n%2!=0)throw new TypeError("[FlatPair: removeByValue] items length must be even number");for(let i=1;i<n;i+=2)if(e(r[i],t))return r.splice(i-1,2),!0;return!1}function f(e,r,t){const n=e.length;if(n%2!=0)throw new TypeError("[FlatPair: forEach] items length must be even number");for(let i=0;i<n;i+=2)i in e&&r.call(t,e[i+1],e[i],i,e)}function a(e){e.length=0}function h(e,r){const t=e.length;if(t%2!=0)throw new TypeError("[FlatPair: find] items length must be even number");for(let n=0;n<t;n+=2){if(r(e[n+1],e[n],n,e))return[e[n],e[n+1]]}}function m(e,r){const t=e.length;if(t%2!=0)throw new TypeError("[FlatPair: findIndex] items length must be even number");for(let n=0;n<t;n+=2){if(r(e[n+1],e[n],n,e))return n}return-1}class c{static from(e){if("[object Map]"!==Object.prototype.toString.call(e))throw new TypeError("[FlatPair: from] Argument must be a Map");const r=[];return e.forEach((e,t)=>r.push(t,e)),new c(r)}t=[];constructor(e){if(e.length%2!=0)throw new TypeError("[FlatPair: constructor] items length must be even number");this.t=e.slice()}get size(){return this.t.length/2}get array(){return this.t}add(e,r){return t(this.t,e,r),this}hasByValue(e){return i(this.t,e)}remove(e){return s(this.t,e)}removeByValue(e){return l(this.t,e)}get(e){return u(this.t,e)}getByValue(e){return o(this.t,e)}find(e){return h(this.t,e)}findIndex(e){return m(this.t,e)}clear(){this.t.length=0}has(e){return n(this.t,e)}forEach(e,r){f(this.t,e,r)}*keys(){for(let e=0;e<this.t.length;e+=2)yield this.t[e]}*values(){for(let e=1;e<this.t.length;e+=2)yield this.t[e]}*entries(){for(let e=0;e<this.t.length;e+=2)yield[this.t[e],this.t[e+1]]}[Symbol.iterator](){return this.entries()}}class y{add(e,r,n){t(e,r,n)}remove(e,r){return s(e,r)}get(e,r){return u(e,r)}getByValue(e,r){return o(e,r)}find(e,r){return h(e,r)}findIndex(e,r){return m(e,r)}removeByValue(e,r){return l(e,r)}forEach(e,r,t){f(e,r,t)}*keys(e){for(let r=0;r<e.length;r+=2)yield e[r]}*values(e){for(let r=1;r<e.length;r+=2)yield e[r]}*entries(e){for(let r=0;r<e.length;r+=2)yield[e[r],e[r+1]]}clear(e){e.length=0}has(e,r){return n(e,r)}hasByValue(e,r){return i(e,r)}}export{c as FlatPair,y as FlatPairOperator,t as add,a as clear,h as find,m as findIndex,f as forEach,u as get,o as getByValue,n as has,i as hasByValue,s as remove,l as removeByValue,r as size};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "flat-pair",
-	"version": "1.0.1",
+	"version": "1.2.0",
 	"author": {
 		"name": "Kasukabe Tsumugi",
 		"email": "futami16237@gmail.com"