flat-pair 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kasukabe tsumugi
+
+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,153 @@
+# flat-pair
+
+[![npm version](https://img.shields.io/npm/v/flat-pair.svg)](https://www.npmjs.com/package/flat-pair) [![npm downloads](http://img.shields.io/npm/dm/flat-pair.svg)](https://npmcharts.com/compare/flat-pair,token-types?start=1200&interval=30)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/59dd6795e61949fb97066ca52e6097ef)](https://www.codacy.com/app/Borewit/flat-pair?utm_source=github.com&utm_medium=referral&utm_content=Borewit/flat-pair&utm_campaign=Badge_Grade)
+
+A lightweight TypeScript library for storing key-value pairs using arrays. Provides serializable storage with efficient value-based lookups and zero-cost static methods.
+
+For more awesome packages, check out [my homepage💛](https://baendlorel.github.io/?repoType=npm)
+
+## Features
+
+- 🔍 **Bidirectional Search**: Find keys by values and values by keys
+- 📦 **Serializable**: Easy JSON serialization/deserialization
+- 🛡️ **Type Safe**: Full TypeScript support with generic types
+- 🎯 **Zero Cost**: Static methods available for minimal overhead
+- ⚡ **Lightweight**: No dependencies, minimal bundle size
+
+## Installation
+
+```bash
+npm install flat-pair
+# or
+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();
+```
+
+### 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
+```
+
+### forEach
+
+`forEach` iterates pairs and follows the callback signature `(value, key, index, arr)` and accepts an optional `thisArg`.
+
+```typescript
+fp.forEach(
+  function (value, key, index, arr) {
+    console.log(index, key, value, arr === (fp as any).items);
+  },
+  { myThis: true }
+);
+```
+
+### 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'
+
+// Remove and other operations
+remove(items, 'age'); // returns true
+console.log(size(items)); // 1
+clear(items); // empties the array
+```
+
+### Using FlatPairOperator Class (For fixed type hint)
+
+```typescript
+import { FlatPairOperator } from 'flat-pair';
+
+const operator = new FlatPairOperator<string, number>();
+const items: any[] = [];
+
+operator.add(items, 'score', 100);
+operator.add(items, 'level', 5);
+
+console.log(operator.find(items, 'score')); // 100
+console.log(operator.findByValue(items, 5)); // 'level'
+```
+
+## Performance
+
+FlatPair uses a simple array structure `[key1, value1, key2, value2, ...]` which provides:
+
+- **Memory Efficiency**: No object overhead per pair
+- **Serialization**: Direct JSON support
+- **Cache Friendly**: Contiguous memory layout
+- **Predictable**: O(n) operations with low constant factors
+
+> Note: For large datasets, consider using a Map or Object for O(1) lookups instead of this package.
+
+## License
+
+MIT © Kasukabe Tsumugi

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+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;
+    constructor(items: any[]);
+    get size(): number;
+    /**
+     * Will check if the key already exists, if so then do nothing.
+     */
+    add(key: K, value: V): this;
+    remove(key: K): boolean;
+    removeByValue(value: V): boolean;
+    find(key: K): V | undefined;
+    findByValue(value: V): K | undefined;
+    at(index: number): [K, V] | undefined;
+    clear(): void;
+    forEach(callback: (value: V, key: K, index: number, arr: any[]) => void, thisArg?: any): void;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[K, V]>;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}
+
+/**
+ * Creates an static operator
+ */
+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;
+    removeByValue(items: any[], value: V): boolean;
+    forEach(items: any[], callback: (value: V, key: K, index: number, arr: any[]) => void, thisArg?: any): void;
+    at(items: any[], index: number): [K, V] | undefined;
+    keys(items: any[]): IterableIterator<K>;
+    values(items: any[]): IterableIterator<V>;
+    entries(items: any[]): IterableIterator<[K, V]>;
+    clear(items: any[]): void;
+}
+
+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 remove<K>(items: any[], key: K): boolean;
+declare function removeByValue<K, V>(items: any[], value: V): boolean;
+declare function forEach<K, V>(items: any[], callback: (value: V, key: K, index: number, arr: any[]) => void, thisArg?: any): void;
+declare function at<K, V>(items: any[], index: number): [K, V] | undefined;
+declare function clear(items: any[]): void;
+
+export { FlatPair, FlatPairOperator, add, at, clear, find, findByValue, forEach, remove, removeByValue, size };

package/dist/index.mjs

@@ -0,0 +1 @@
+function t(t,r,e){for(let e=0;e<t.length;e+=2)if(t[e]===r)return;t.push(r,e)}function r(t){if(t.length%2!=0)throw new Error("Invalid items length, must be even number");return t.length/2}function e(t,r){for(let e=0;e<t.length;e+=2)if(t[e]===r)return t[e+1]}function n(t,r){for(let e=1;e<t.length;e+=2)if(t[e]===r)return t[e-1]}function i(t,r){for(let e=0;e<t.length;e+=2)if(t[e]===r)return t.splice(e,2),!0;return!1}function u(t,r){for(let e=1;e<t.length;e+=2)if(t[e]===r)return t.splice(e-1,2),!0;return!1}function o(t,r,e){let n=0;for(let i=0;i<t.length;i+=2)r.call(e,t[i+1],t[i],n,t),n++}function s(t,r){if(r<0)return;const e=2*r;return e+1>=t.length?void 0:[t[e],t[e+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 r=[];return t.forEach((t,e)=>r.push(e,t)),new l(r)}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(r,e){return t(this.items,r,e),this}remove(t){return i(this.items,t)}removeByValue(t){return u(this.items,t)}find(t){return e(this.items,t)}findByValue(t){return n(this.items,t)}at(t){return s(this.items,t)}clear(){this.items.length=0}forEach(t,r){o(this.items,t,r)}*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 h{add(r,e,n){t(r,e,n)}remove(t,r){return i(t,r)}find(t,r){return e(t,r)}findByValue(t,r){return n(t,r)}removeByValue(t,r){return u(t,r)}forEach(t,r,e){return o(t,r,e)}at(t,r){return s(t,r)}*keys(t){for(let r=0;r<t.length;r+=2)yield t[r]}*values(t){for(let r=1;r<t.length;r+=2)yield t[r]}*entries(t){for(let r=0;r<t.length;r+=2)yield[t[r],t[r+1]]}clear(t){t.length=0}}export{l as FlatPair,h as FlatPairOperator,t as add,s as at,f as clear,e as find,n as findByValue,o as forEach,i as remove,u as removeByValue,r as size};

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "flat-pair",
+	"version": "1.0.0",
+	"author": {
+		"name": "Kasukabe Tsumugi",
+		"email": "futami16237@gmail.com"
+	},
+	"purpose": "npm",
+	"description": "Using array to save pairs. Serializable and easier to find, locate by value. Provide static methods, use it at 0 cost!",
+	"description_zh": "用数组来保存键值对。可序列化且更容易通过值查找、定位。提供静态方法，0成本使用！",
+	"type": "module",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		"types": "./dist/index.d.ts",
+		"import": "./dist/index.mjs",
+		"default": "./dist/index.mjs"
+	},
+	"files": [
+		"dist"
+	],
+	"homepage": "https://github.com/baendlorel/flat-pair#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/baendlorel/flat-pair"
+	},
+	"keywords": [
+		"typescript",
+		"javascript"
+	],
+	"scripts": {
+		"test": "clear & vitest",
+		"lint": "oxlint .",
+		"cover": "clear & vitest --coverage",
+		"build": "node ./.scripts/rollup.mjs"
+	},
+	"license": "MIT",
+	"devDependencies": {
+		"@rollup/plugin-alias": "^5.1.1",
+		"@rollup/plugin-commonjs": "^28.0.6",
+		"@rollup/plugin-node-resolve": "^16.0.1",
+		"@rollup/plugin-replace": "^6.0.2",
+		"@rollup/plugin-terser": "^0.4.4",
+		"@rollup/plugin-typescript": "^12.1.4",
+		"@types/node": "^24.6.2",
+		"@vitest/coverage-v8": "^3.2.4",
+		"oxlint": "^1.19.0",
+		"prettier": "^3.6.2",
+		"rimraf": "^6.0.1",
+		"rollup": "^4.52.4",
+		"rollup-plugin-dts": "^6.2.3",
+		"rollup-plugin-func-macro": "^1.1.0",
+		"tslib": "^2.8.1",
+		"typescript": "^5.9.3",
+		"vitest": "^3.2.4"
+	}
+}