nv-facutil-has 1.0.0

package/README.md

@@ -0,0 +1,417 @@
+# has - JavaScript Property Inspector
+
+A comprehensive utility for checking and inspecting object properties and prototype chains in JavaScript.
+
+## Installation
+
+```javascript
+const has = require('nv-facutil-has');
+```
+
+## ⚠️ Important Usage Note
+
+**The main function `has()` is designed for production use. All other utility functions are intended for CLI tools, testing frameworks, and debugging/inspection purposes only.**
+
+These inspection utilities provide deep introspection capabilities that are useful for:
+- Interactive REPL/CLI environments
+- Test assertions and debugging
+- Object structure analysis
+- Educational purposes
+
+They are **not recommended** for production application logic due to performance considerations and complexity.
+
+---
+
+## Main Function (Production Use)
+
+### `has(object, key, only_own=false)`
+
+Checks if an object has a specific property.
+
+**Parameters:**
+- `object`: The object to check
+- `key`: The property key (string or symbol)
+- `only_own` (default: `false`): If `true`, checks only own properties; if `false`, includes prototype chain
+
+**Returns:** `boolean`
+
+**Examples:**
+
+```javascript
+const obj = { a: 1, b: 2 };
+
+// Check with prototype chain
+has(obj, 'a');           // true
+has(obj, 'toString');    // true (inherited from Object.prototype)
+
+// Check only own properties
+has(obj, 'a', true);     // true
+has(obj, 'toString', true); // false
+
+// Safe with null/undefined
+has(null, 'prop');       // false
+has(undefined, 'prop');  // false
+```
+
+---
+
+## Inspection Utilities (CLI/Testing Only)
+
+### `slow(object, key, dig=Infinity)`
+
+Searches for a property within a specified depth range in the prototype chain.
+
+**Parameters:**
+- `object`: The object to search
+- `key`: The property key to find
+- `dig` (default: `Infinity`): Maximum depth to search
+  - `0`: Own properties only
+  - `n`: Search up to n levels in prototype chain
+  - `Infinity`: Search entire chain
+
+**Returns:** `boolean`
+
+**Examples:**
+
+```javascript
+const grandparent = { a: 1 };
+const parent = Object.create(grandparent);
+parent.b = 2;
+const child = Object.create(parent);
+child.c = 3;
+
+has.slow(child, 'c', 0);        // true (own property)
+has.slow(child, 'b', 0);        // false (not own)
+has.slow(child, 'b', 1);        // true (within 1 level)
+has.slow(child, 'a', 2);        // true (within 2 levels)
+has.slow(child, 'a', 1);        // false (need 2 levels)
+has.slow(child, 'a', Infinity); // true (search all)
+```
+
+---
+
+### `exact(object, key, depth=Infinity)`
+
+Checks if a property exists at an exact depth in the prototype chain.
+
+**Parameters:**
+- `object`: The object to check
+- `key`: The property key
+- `depth`: Exact prototype chain depth
+  - `0`: Object's own property
+  - `n`: Property at exactly n levels up
+  - `Infinity`: Anywhere in chain
+
+**Returns:** `boolean`
+
+**Examples:**
+
+```javascript
+const gp = { a: 1 };
+const p = Object.create(gp);
+p.b = 2;
+const c = Object.create(p);
+c.c = 3;
+
+has.exact(c, 'c', 0);  // true (own property)
+has.exact(c, 'b', 0);  // false (at level 1)
+has.exact(c, 'b', 1);  // true (exactly at level 1)
+has.exact(c, 'a', 1);  // false (at level 2, not 1)
+has.exact(c, 'a', 2);  // true (exactly at level 2)
+```
+
+---
+
+### `get_proto_chain(object)`
+
+Returns the complete prototype chain as an array.
+
+**Parameters:**
+- `object`: The object to inspect
+
+**Returns:** `Array` - Array of objects in the prototype chain
+
+**Examples:**
+
+```javascript
+const parent = { x: 1 };
+const child = Object.create(parent);
+child.y = 2;
+
+const chain = has.get_proto_chain(child);
+// [child, parent, Object.prototype]
+
+console.log(chain.length);  // 3
+console.log(chain[0] === child);   // true
+console.log(chain[1] === parent);  // true
+```
+
+---
+
+### `get_prop_descs(object, split_layer=false)`
+
+Retrieves property descriptors from the prototype chain.
+
+**Parameters:**
+- `object`: The object to inspect
+- `split_layer` (default: `false`): Output format
+  - `false`: Single object with all descriptors merged
+  - `true`: Array of `{object, descriptors}` per layer
+
+**Returns:** `Object` or `Array`
+
+**Examples:**
+
+```javascript
+const obj = { a: 1 };
+Object.defineProperty(obj, 'b', {
+    value: 2,
+    writable: false,
+    enumerable: true
+});
+
+// Merged format (default)
+const descs = has.get_prop_descs(obj, false);
+console.log(descs.a);
+// { value: 1, writable: true, enumerable: true, configurable: true }
+
+console.log(descs.b.writable);  // false
+
+// Layer-by-layer format
+const layers = has.get_prop_descs(obj, true);
+layers.forEach((layer, i) => {
+    console.log(`Layer ${i}:`, Object.keys(layer.descriptors));
+});
+```
+
+---
+
+### `get_all_keys(object, split_layer=false, enable_grouping=false)`
+
+Gets all property keys (including symbols and non-enumerable) from the prototype chain.
+
+**Parameters:**
+- `object`: The object to inspect
+- `split_layer` (default: `false`): Separate by prototype layers
+- `enable_grouping` (default: `false`): Group by property characteristics
+
+**Returns:** `Array` or `Object`
+
+**Property Signature Format (when `enable_grouping=true`):**
+- `k-__v-wec`: string key, data property, writable+enumerable+configurable
+- `k-g__-_ec`: string key, getter only, enumerable+configurable
+- `k-gs_-_e_`: string key, getter+setter, enumerable only
+- `y-__v-wec`: symbol key, data property, writable+enumerable+configurable
+
+Format: `{keyType}-{propType}-{flags}`
+- Key type: `k` (string) or `y` (symbol)
+- Property type: `__v` (data), `g__` (getter), `_s_` (setter), `gs_` (both)
+- Flags: `w` (writable), `e` (enumerable), `c` (configurable), `_` (absent)
+
+**Examples:**
+
+```javascript
+const obj = { a: 1 };
+Object.defineProperty(obj, 'getter', {
+    get: () => 'value',
+    enumerable: true
+});
+const sym = Symbol('test');
+obj[sym] = 'symbol value';
+
+// Simple list
+const keys = has.get_all_keys(obj);
+console.log(keys);  // ['a', 'getter', Symbol(test)]
+
+// Grouped by characteristics
+const grouped = has.get_all_keys(obj, false, true);
+console.log(grouped);
+// {
+//   'k-__v-wec': ['a'],
+//   'k-g__-_ec': ['getter'],
+//   'y-__v-wec': [Symbol(test)]
+// }
+
+// Split by layers
+const parent = { x: 10 };
+const child = Object.create(parent);
+child.y = 20;
+
+const layers = has.get_all_keys(child, true);
+console.log(layers);
+// [
+//   ['y'],      // Layer 0: child's own
+//   ['x']       // Layer 1: parent's own
+// ]
+```
+
+---
+
+### `nestify(object)`
+
+Converts a flat object into a nested prototype chain structure.
+
+**Parameters:**
+- `object`: A flat object to convert
+
+**Returns:** Object with properties distributed across prototype chain
+
+**How it works:**
+- First property → deepest prototype
+- Middle properties → intermediate prototypes
+- Last property → object's own property
+
+**Examples:**
+
+```javascript
+const flat = { a: 100, b: 200, c: 300 };
+const nested = has.nestify(flat);
+
+// Resulting structure:
+// nested (own): { c: 300 }
+//   └─ prototype (empty layer)
+//       └─ prototype: { b: 200 }
+//           └─ prototype: { a: 100 }
+
+console.log(nested.c);  // 300 (own property)
+console.log(nested.b);  // 200 (from prototype)
+console.log(nested.a);  // 100 (from deeper prototype)
+
+console.log(Object.hasOwn(nested, 'c'));  // true
+console.log(Object.hasOwn(nested, 'b'));  // false
+console.log(Object.hasOwn(nested, 'a'));  // false
+
+// Verify depths
+has.exact(nested, 'c', 0);  // true
+has.exact(nested, 'b', 2);  // true
+has.exact(nested, 'a', 3);  // true
+```
+
+---
+
+### `flatify(object)`
+
+Converts a nested prototype chain back into a flat object.
+
+**Parameters:**
+- `object`: Object with prototype chain to flatten
+
+**Returns:** Flat object with all properties merged
+
+**Examples:**
+
+```javascript
+const nested = has.nestify({ a: 1, b: 2, c: 3 });
+const flat = has.flatify(nested);
+
+console.log(flat);  // { c: 3, b: 2, a: 1 }
+
+// All values preserved
+console.log(flat.a === 1);  // true
+console.log(flat.b === 2);  // true
+console.log(flat.c === 3);  // true
+
+// Round-trip preservation
+const original = { x: 10, y: 20, z: 30 };
+const restored = has.flatify(has.nestify(original));
+// restored contains all original properties and values
+```
+
+---
+
+## Use Cases
+
+### Production Code
+
+```javascript
+// Simple property existence check
+if (has(config, 'database')) {
+    // Use config.database
+}
+
+// Check own properties only
+if (has(userInput, 'password', true)) {
+    // Process password
+}
+```
+
+### Testing & Debugging
+
+```javascript
+// In a test framework
+describe('Object structure', () => {
+    it('should have property at correct depth', () => {
+        const obj = createComplexObject();
+        assert(has.exact(obj, 'deepProp', 3));
+    });
+    
+    it('should have all expected keys', () => {
+        const keys = has.get_all_keys(obj, false, true);
+        assert(keys['k-__v-wec'].includes('importantProp'));
+    });
+});
+
+// In CLI inspection tool
+function inspect(obj) {
+    const chain = has.get_proto_chain(obj);
+    console.log(`Prototype chain depth: ${chain.length}`);
+    
+    const descs = has.get_prop_descs(obj, true);
+    descs.forEach((layer, i) => {
+        console.log(`Level ${i}:`, Object.keys(layer.descriptors));
+    });
+}
+```
+
+### Object Analysis
+
+```javascript
+// Analyze object structure
+function analyzeObject(obj) {
+    const allKeys = has.get_all_keys(obj, false, true);
+    
+    console.log('Property distribution:');
+    for (const [sig, keys] of Object.entries(allKeys)) {
+        console.log(`${sig}: ${keys.length} properties`);
+    }
+    
+    const layers = has.get_proto_chain(obj);
+    console.log(`\nPrototype depth: ${layers.length}`);
+}
+```
+
+---
+
+## Performance Considerations
+
+**Main function `has()`:**
+- Optimized for production use
+- O(1) for own properties
+- O(n) for prototype chain (where n = chain depth)
+
+**Inspection utilities:**
+- May perform multiple traversals
+- Use reflection APIs (getOwnPropertyDescriptors, etc.)
+- Not optimized for high-frequency calls
+- Best suited for development/debugging scenarios
+
+---
+
+## API Summary
+
+| Function | Purpose | Production Use |
+|----------|---------|----------------|
+| `has(o, key, only_own)` | Check property existence | ✅ Yes |
+| `slow(o, key, dig)` | Search within depth range | ❌ No (CLI/Testing) |
+| `exact(o, key, depth)` | Check exact depth | ❌ No (CLI/Testing) |
+| `get_proto_chain(o)` | Get prototype chain | ❌ No (CLI/Testing) |
+| `get_prop_descs(o, split)` | Get property descriptors | ❌ No (CLI/Testing) |
+| `get_all_keys(o, split, group)` | Get all keys with details | ❌ No (CLI/Testing) |
+| `nestify(o)` | Flatten to chain | ❌ No (CLI/Testing) |
+| `flatify(o)` | Chain to flat | ❌ No (CLI/Testing) |
+
+---
+
+## License
+
+MIT

package/TEST/tst-nest-flat.js

@@ -0,0 +1,235 @@
+const has = require('../index.js');
+
+console.log("=".repeat(60));
+console.log("=== nestify() and flatify() Detailed Tests ===");
+console.log("=".repeat(60));
+
+// Helper function to display prototype chain
+function showProtoChain(obj, name = "obj") {
+    console.log(`\nPrototype chain for ${name}:`);
+    let current = obj;
+    let depth = 0;
+    
+    while (current != null && depth < 10) {
+        const ownKeys = Object.keys(current);
+        if (ownKeys.length > 0 || depth === 0) {
+            const props = ownKeys.map(k => `${k}: ${current[k]}`).join(', ');
+            console.log(`  Level ${depth}: {${props || 'empty'}}`);
+        }
+        current = Object.getPrototypeOf(current);
+        depth++;
+        if (current === Object.prototype) {
+            console.log(`  Level ${depth}: Object.prototype`);
+            break;
+        }
+    }
+}
+
+// Test 1: Empty object
+console.log("\n" + "=".repeat(60));
+console.log("Test 1: Empty object");
+console.log("=".repeat(60));
+const empty = {};
+const nestedEmpty = has.nestify(empty);
+const flatEmpty = has.flatify(nestedEmpty);
+console.log("Original:", empty);
+console.log("Nestified:", nestedEmpty);
+console.log("Flatified:", flatEmpty);
+console.log("Match:", JSON.stringify(flatEmpty) === JSON.stringify(empty));
+
+// Test 2: Single property
+console.log("\n" + "=".repeat(60));
+console.log("Test 2: Single property");
+console.log("=".repeat(60));
+const single = { a: 100 };
+const nestedSingle = has.nestify(single);
+const flatSingle = has.flatify(nestedSingle);
+console.log("Original:", single);
+console.log("Nestified:", nestedSingle);
+console.log("Flatified:", flatSingle);
+console.log("Own keys in nested:", Object.keys(nestedSingle));
+console.log("Match:", flatSingle.a === 100);
+
+// Test 3: Two properties
+console.log("\n" + "=".repeat(60));
+console.log("Test 3: Two properties {a:100, b:200}");
+console.log("=".repeat(60));
+const two = { a: 100, b: 200 };
+const nestedTwo = has.nestify(two);
+const flatTwo = has.flatify(nestedTwo);
+console.log("Original:", two);
+showProtoChain(nestedTwo, "nestedTwo");
+console.log("Flatified:", flatTwo);
+console.log("Values accessible:", nestedTwo.a, nestedTwo.b);
+console.log("b is own?", Object.hasOwn(nestedTwo, 'b'));
+console.log("a is own?", Object.hasOwn(nestedTwo, 'a'));
+console.log("Match:", flatTwo.a === 100 && flatTwo.b === 200);
+
+// Test 4: Three properties
+console.log("\n" + "=".repeat(60));
+console.log("Test 4: Three properties {a:1, b:2, c:3}");
+console.log("=".repeat(60));
+const three = { a: 1, b: 2, c: 3 };
+const nestedThree = has.nestify(three);
+const flatThree = has.flatify(nestedThree);
+console.log("Original:", three);
+showProtoChain(nestedThree, "nestedThree");
+console.log("Flatified:", flatThree);
+console.log("All values accessible:", nestedThree.a, nestedThree.b, nestedThree.c);
+console.log("Match:", flatThree.a === 1 && flatThree.b === 2 && flatThree.c === 3);
+
+// Test 5: Five properties
+console.log("\n" + "=".repeat(60));
+console.log("Test 5: Five properties");
+console.log("=".repeat(60));
+const five = { a: 1, b: 2, c: 3, d: 4, e: 5 };
+const nestedFive = has.nestify(five);
+const flatFive = has.flatify(nestedFive);
+console.log("Original:", five);
+showProtoChain(nestedFive, "nestedFive");
+console.log("Flatified:", flatFive);
+console.log("Match:", JSON.stringify(flatFive) === JSON.stringify({a:1, b:2, c:3, d:4, e:5}));
+
+// Test 6: Different value types
+console.log("\n" + "=".repeat(60));
+console.log("Test 6: Different value types");
+console.log("=".repeat(60));
+const mixed = { 
+    num: 42, 
+    str: "hello", 
+    bool: true, 
+    nil: null,
+    arr: [1, 2, 3],
+    obj: { nested: "value" }
+};
+const nestedMixed = has.nestify(mixed);
+const flatMixed = has.flatify(nestedMixed);
+console.log("Original:", mixed);
+console.log("Flatified:", flatMixed);
+console.log("num match:", flatMixed.num === 42);
+console.log("str match:", flatMixed.str === "hello");
+console.log("bool match:", flatMixed.bool === true);
+console.log("nil match:", flatMixed.nil === null);
+console.log("arr match:", JSON.stringify(flatMixed.arr) === JSON.stringify([1,2,3]));
+console.log("obj match:", JSON.stringify(flatMixed.obj) === JSON.stringify({nested:"value"}));
+
+// Test 7: Property depth testing with exact()
+console.log("\n" + "=".repeat(60));
+console.log("Test 7: Property depth testing");
+console.log("=".repeat(60));
+const depth = { first: 1, second: 2, third: 3, fourth: 4 };
+const nestedDepth = has.nestify(depth);
+console.log("Original:", depth);
+showProtoChain(nestedDepth, "nestedDepth");
+
+console.log("\nDepth checks with exact():");
+console.log("fourth at depth 0:", has.exact(nestedDepth, 'fourth', 0));
+console.log("fourth at depth 1:", has.exact(nestedDepth, 'fourth', 1));
+console.log("third at depth 0:", has.exact(nestedDepth, 'third', 0));
+console.log("third at depth 2:", has.exact(nestedDepth, 'third', 2));
+console.log("second at depth 2:", has.exact(nestedDepth, 'second', 2));
+console.log("first at depth 3:", has.exact(nestedDepth, 'first', 3));
+
+// Test 8: Round-trip preservation
+console.log("\n" + "=".repeat(60));
+console.log("Test 8: Round-trip preservation");
+console.log("=".repeat(60));
+const original = { x: 10, y: 20, z: 30, w: 40 };
+const step1 = has.nestify(original);
+const step2 = has.flatify(step1);
+const step3 = has.nestify(step2);
+const step4 = has.flatify(step3);
+
+console.log("Original:", original);
+console.log("After nest->flat:", step2);
+console.log("After nest->flat->nest->flat:", step4);
+console.log("Values preserved:", 
+    step4.x === 10 && step4.y === 20 && step4.z === 30 && step4.w === 40);
+
+// Test 9: null and undefined
+console.log("\n" + "=".repeat(60));
+console.log("Test 9: null and undefined handling");
+console.log("=".repeat(60));
+console.log("nestify(null):", has.nestify(null));
+console.log("nestify(undefined):", has.nestify(undefined));
+console.log("flatify(null):", has.flatify(null));
+console.log("flatify(undefined):", has.flatify(undefined));
+
+// Test 10: flatify on regular object with prototype
+console.log("\n" + "=".repeat(60));
+console.log("Test 10: flatify on object with custom prototype");
+console.log("=".repeat(60));
+const proto = { inherited: "from proto" };
+const child = Object.create(proto);
+child.own = "own property";
+const flatChild = has.flatify(child);
+console.log("Child object with prototype");
+console.log("child.own:", child.own);
+console.log("child.inherited:", child.inherited);
+console.log("Flatified:", flatChild);
+console.log("Has both properties:", flatChild.own === "own property" && flatChild.inherited === "from proto");
+
+// Test 11: Property order preservation
+console.log("\n" + "=".repeat(60));
+console.log("Test 11: Property order");
+console.log("=".repeat(60));
+const ordered = { z: 1, y: 2, x: 3, w: 4, v: 5 };
+const nestedOrdered = has.nestify(ordered);
+const flatOrdered = has.flatify(nestedOrdered);
+console.log("Original keys:", Object.keys(ordered));
+console.log("Flatified keys:", Object.keys(flatOrdered));
+console.log("Note: Order might differ but values should match");
+console.log("All values present:", 
+    flatOrdered.z === 1 && flatOrdered.y === 2 && 
+    flatOrdered.x === 3 && flatOrdered.w === 4 && flatOrdered.v === 5);
+
+// Test 12: Using slow() on nestified objects
+console.log("\n" + "=".repeat(60));
+console.log("Test 12: Using slow() on nestified objects");
+console.log("=".repeat(60));
+const test = { a: 1, b: 2, c: 3 };
+const nestedTest = has.nestify(test);
+console.log("Original:", test);
+console.log("\nUsing slow() to find properties:");
+console.log("slow(nested, 'c', 0):", has.slow(nestedTest, 'c', 0));  // own
+console.log("slow(nested, 'c', 1):", has.slow(nestedTest, 'c', 1));  // within 1 level
+console.log("slow(nested, 'b', 1):", has.slow(nestedTest, 'b', 1));  // need to check deeper
+console.log("slow(nested, 'b', 2):", has.slow(nestedTest, 'b', 2));  
+console.log("slow(nested, 'a', 3):", has.slow(nestedTest, 'a', 3));  
+console.log("slow(nested, 'a', Infinity):", has.slow(nestedTest, 'a', Infinity));
+
+// Test 13: Performance test
+console.log("\n" + "=".repeat(60));
+console.log("Test 13: Performance comparison");
+console.log("=".repeat(60));
+
+const large = {};
+for (let i = 0; i < 100; i++) {
+    large[`key${i}`] = i;
+}
+
+console.time("nestify 100 properties");
+const nestedLarge = has.nestify(large);
+console.timeEnd("nestify 100 properties");
+
+console.time("flatify 100 properties");
+const flatLarge = has.flatify(nestedLarge);
+console.timeEnd("flatify 100 properties");
+
+console.log("All properties preserved:", Object.keys(flatLarge).length === 100);
+
+// Test 14: Edge case - Object with numeric keys
+console.log("\n" + "=".repeat(60));
+console.log("Test 14: Numeric keys");
+console.log("=".repeat(60));
+const numeric = { 0: "zero", 1: "one", 2: "two" };
+const nestedNumeric = has.nestify(numeric);
+const flatNumeric = has.flatify(nestedNumeric);
+console.log("Original:", numeric);
+console.log("Flatified:", flatNumeric);
+console.log("Match:", flatNumeric[0] === "zero" && flatNumeric[1] === "one" && flatNumeric[2] === "two");
+
+console.log("\n" + "=".repeat(60));
+console.log("=== All tests completed! ===");
+console.log("=".repeat(60));
+

package/TEST/tst.js

@@ -0,0 +1,136 @@
+const has = require('../index.js');
+
+console.log("=== Basic has() Tests ===\n");
+
+// Test 1: Basic own property
+const obj1 = { a: 1, b: 2 };
+console.log("Test 1: Own property");
+console.log("has(obj1, 'a', true):", has(obj1, 'a', true));   // true
+console.log("has(obj1, 'a', false):", has(obj1, 'a', false)); // true
+console.log("has(obj1, 'c', true):", has(obj1, 'c', true));   // false
+
+// Test 2: Prototype chain
+const parent = { x: 10 };
+const child = Object.create(parent);
+child.y = 20;
+
+console.log("\nTest 2: Prototype chain");
+console.log("has(child, 'y', true):", has(child, 'y', true));   // true (own)
+console.log("has(child, 'x', true):", has(child, 'x', true));   // false (inherited)
+console.log("has(child, 'x', false):", has(child, 'x', false)); // true (in chain)
+
+// Test 3: null/undefined handling
+console.log("\nTest 3: null/undefined");
+console.log("has(null, 'a'):", has(null, 'a'));         // false
+console.log("has(undefined, 'a'):", has(undefined, 'a')); // false
+
+console.log("\n" + "=".repeat(50));
+console.log("=== Detailed has.slow() Tests ===\n");
+
+// Setup: 3-level prototype chain
+const grandparent = { level: 'grandparent', gp: 'GP' };
+const parent2 = Object.create(grandparent);
+parent2.level = 'parent';
+parent2.p = 'P';
+const child2 = Object.create(parent2);
+child2.level = 'child';
+child2.c = 'C';
+
+console.log("Test Setup: 3-level chain");
+console.log("child2 -> parent2 -> grandparent -> Object.prototype");
+console.log("child2 has: { level: 'child', c: 'C' }");
+console.log("parent2 has: { level: 'parent', p: 'P' }");
+console.log("grandparent has: { level: 'grandparent', gp: 'GP' }");
+
+// Test 4: dig = 0 (own property only)
+console.log("\nTest 4: dig = 0 (own property only)");
+console.log("slow(child2, 'c', 0):", has.slow(child2, 'c', 0));      // true
+console.log("slow(child2, 'level', 0):", has.slow(child2, 'level', 0)); // true
+console.log("slow(child2, 'p', 0):", has.slow(child2, 'p', 0));      // false
+console.log("slow(child2, 'gp', 0):", has.slow(child2, 'gp', 0));    // false
+console.log("slow(child2, 'toString', 0):", has.slow(child2, 'toString', 0)); // false
+
+// Test 5: dig = 1 (search 1 level up)
+console.log("\nTest 5: dig = 1 (search 1 level up)");
+console.log("slow(child2, 'c', 1):", has.slow(child2, 'c', 1));      // true (own)
+console.log("slow(child2, 'p', 1):", has.slow(child2, 'p', 1));      // true (parent)
+console.log("slow(child2, 'gp', 1):", has.slow(child2, 'gp', 1));    // false (grandparent)
+console.log("slow(child2, 'level', 1):", has.slow(child2, 'level', 1)); // true (own)
+
+// Test 6: dig = 2 (search 2 levels up)
+console.log("\nTest 6: dig = 2 (search 2 levels up)");
+console.log("slow(child2, 'c', 2):", has.slow(child2, 'c', 2));      // true
+console.log("slow(child2, 'p', 2):", has.slow(child2, 'p', 2));      // true
+console.log("slow(child2, 'gp', 2):", has.slow(child2, 'gp', 2));    // true (grandparent)
+console.log("slow(child2, 'toString', 2):", has.slow(child2, 'toString', 2)); // false
+
+// Test 7: dig = 3 (search 3 levels up)
+console.log("\nTest 7: dig = 3 (search 3 levels up)");
+console.log("slow(child2, 'gp', 3):", has.slow(child2, 'gp', 3));    // true
+console.log("slow(child2, 'toString', 3):", has.slow(child2, 'toString', 3)); // true (Object.prototype)
+
+// Test 8: dig = Infinity (entire chain)
+console.log("\nTest 8: dig = Infinity (entire chain)");
+console.log("slow(child2, 'c', Infinity):", has.slow(child2, 'c', Infinity));  // true
+console.log("slow(child2, 'p', Infinity):", has.slow(child2, 'p', Infinity));  // true
+console.log("slow(child2, 'gp', Infinity):", has.slow(child2, 'gp', Infinity)); // true
+console.log("slow(child2, 'toString', Infinity):", has.slow(child2, 'toString', Infinity)); // true
+console.log("slow(child2, 'nonexistent', Infinity):", has.slow(child2, 'nonexistent', Infinity)); // false
+
+// Test 9: Edge cases
+console.log("\nTest 9: Edge cases");
+console.log("slow(null, 'a', 0):", has.slow(null, 'a', 0));          // false
+console.log("slow(undefined, 'a', 1):", has.slow(undefined, 'a', 1)); // false
+console.log("slow({}, 'toString', 0):", has.slow({}, 'toString', 0)); // false (inherited)
+console.log("slow({}, 'toString', 1):", has.slow({}, 'toString', 1)); // true (Object.prototype)
+
+// Test 10: Array and built-in objects
+console.log("\nTest 10: Arrays");
+const arr = [1, 2, 3];
+arr.custom = 'value';
+console.log("slow(arr, 'custom', 0):", has.slow(arr, 'custom', 0));   // true
+console.log("slow(arr, '0', 0):", has.slow(arr, '0', 0));             // true (index)
+console.log("slow(arr, 'length', 0):", has.slow(arr, 'length', 0));   // true
+console.log("slow(arr, 'push', 0):", has.slow(arr, 'push', 0));       // false
+console.log("slow(arr, 'push', 1):", has.slow(arr, 'push', 1));       // true (Array.prototype)
+
+// Test 11: Deep chain
+console.log("\nTest 11: Deep prototype chain");
+let deep = { level0: true };
+for (let i = 1; i <= 5; i++) {
+    const newObj = Object.create(deep);
+    newObj[`level${i}`] = true;
+    deep = newObj;
+}
+// deep now has 5 levels
+console.log("slow(deep, 'level0', 3):", has.slow(deep, 'level0', 3)); // false (need 5)
+console.log("slow(deep, 'level0', 5):", has.slow(deep, 'level0', 5)); // true
+console.log("slow(deep, 'level2', 3):", has.slow(deep, 'level2', 3)); // true
+console.log("slow(deep, 'level5', 0):", has.slow(deep, 'level5', 0)); // true
+
+// Test 12: Performance comparison
+console.log("\nTest 12: Performance comparison");
+const testObj = Object.create(Object.create({ deepProp: 1 }));
+testObj.shallowProp = 2;
+
+console.time("has() with only_own=false");
+for (let i = 0; i < 100000; i++) {
+    has(testObj, 'deepProp', false);
+}
+console.timeEnd("has() with only_own=false");
+
+console.time("slow() with dig=Infinity");
+for (let i = 0; i < 100000; i++) {
+    has.slow(testObj, 'deepProp', Infinity);
+}
+console.timeEnd("slow() with dig=Infinity");
+
+console.time("slow() with dig=2");
+for (let i = 0; i < 100000; i++) {
+    has.slow(testObj, 'deepProp', 2);
+}
+console.timeEnd("slow() with dig=2");
+
+console.log("\n" + "=".repeat(50));
+console.log("All tests completed!");
+

package/index.js

@@ -0,0 +1,340 @@
+const slow = (o, key, dig = Infinity) => {
+    if (o == null) {
+        return false;
+    }
+    if (dig === 0) {
+        // 只检查自身属性
+        return Object.hasOwn(o, key);
+    } else if (dig === Infinity) {
+        // 检查整个原型链
+        return (key in o);
+    } else {
+        // 沿着原型链向上查找指定层数
+        let current = o;
+        let depth = 0;
+        
+        while (current != null && depth <= dig) {
+            if (Object.hasOwn(current, key)) {
+                return true;
+            }
+            current = Object.getPrototypeOf(current);
+            depth++;
+        }
+        
+        return false;
+    }
+};
+
+const exact = (o, key, depth = Infinity) => {
+    if (o == null) {
+        return false;
+    }
+    if (depth === 0) {
+        // 只检查自身属性
+        return Object.hasOwn(o, key);
+    } else if (depth === Infinity) {
+        // 检查整个原型链
+        return (key in o);
+    } else {
+        // 沿着原型链向上查找指定层数
+        // 必须恰好在第 depth 层有此属性
+        let current = o;
+        
+        // 移动到指定深度
+        for (let i = 0; i < depth; i++) {
+            current = Object.getPrototypeOf(current);
+            if (current == null) {
+                return false; // 原型链不够深
+            }
+        }
+        
+        // 检查该层是否有此属性（自身属性）
+        return Object.hasOwn(current, key);
+    }
+};
+
+const get_proto_chain = (o) => {
+    if (o == null) {
+        return [];
+    }
+    
+    const chain = [];
+    let current = o;
+    
+    while (current != null) {
+        chain.push(current);
+        current = Object.getPrototypeOf(current);
+        
+        // 停在 Object.prototype，不包括 null
+        if (current === Object.prototype) {
+            chain.push(current);
+            break;
+        }
+    }
+    
+    return chain;
+};
+
+const get_prop_descs = (o, split_layer = false) => {
+    if (o == null) {
+        return split_layer ? [] : {};
+    }
+    
+    if (split_layer) {
+        // 按层分割，每层返回 {object, descriptors}
+        const descs = [];
+        let current = o;
+        
+        while (current != null) {
+            const ownDescs = Object.getOwnPropertyDescriptors(current);
+            descs.push({
+                object: current,
+                descriptors: ownDescs
+            });
+            
+            current = Object.getPrototypeOf(current);
+            
+            if (current === Object.prototype) {
+                descs.push({
+                    object: current,
+                    descriptors: Object.getOwnPropertyDescriptors(current)
+                });
+                break;
+            }
+        }
+        
+        return descs;
+    } else {
+        // 不分层，直接合并所有描述符到一个对象
+        const allDescs = {};
+        let current = o;
+        
+        while (current != null) {
+            const ownDescs = Object.getOwnPropertyDescriptors(current);
+            
+            // 只添加还未出现的属性（保留最近层的描述符）
+            for (const key in ownDescs) {
+                if (!(key in allDescs)) {
+                    allDescs[key] = ownDescs[key];
+                }
+            }
+            
+            current = Object.getPrototypeOf(current);
+            
+            if (current === Object.prototype) {
+                break;
+            }
+        }
+        
+        return allDescs;
+    }
+};
+
+// 辅助函数：生成属性特征字符串
+const get_prop_signature = (key, desc) => {
+    const isSymbol = typeof key === 'symbol';
+    const keyType = isSymbol ? 'y' : 'k';
+
+    let propType;
+    if (desc.get || desc.set) {
+        // accessor property
+        const g = desc.get ? 'g' : '_';
+        const s = desc.set ? 's' : '_';
+        propType = `${g}${s}_`;
+    } else {
+        // data property
+        propType = '__v';
+    }
+
+    const w = desc.writable ? 'w' : '_';
+    const e = desc.enumerable ? 'e' : '_';
+    const c = desc.configurable ? 'c' : '_';
+
+    return `${keyType}-${propType}-${w}${e}${c}`;
+};
+
+
+
+const get_all_keys = (
+    o,
+    split_layer = false,
+    enable_grouping = false
+) => {
+    if (o == null) {
+        return split_layer ? [] : (enable_grouping ? {} : []);
+    }
+
+
+
+    if (split_layer) {
+        // 按层分割
+        const layers = [];
+        let current = o;
+
+        while (current != null) {
+            const ownKeys = Object.getOwnPropertyNames(current);
+            const ownSymbols = Object.getOwnPropertySymbols(current);
+            const allKeys = [...ownKeys, ...ownSymbols];
+
+            if (enable_grouping) {
+                const grouped = {};
+                const descs = Object.getOwnPropertyDescriptors(current);
+
+                for (const key of allKeys) {
+                    const desc = descs[key];
+                    const sig = get_prop_signature(key, desc);
+
+                    if (!grouped[sig]) {
+                        grouped[sig] = [];
+                    }
+                    grouped[sig].push(key);
+                }
+
+                layers.push(grouped);
+            } else {
+                layers.push(allKeys);
+            }
+
+            current = Object.getPrototypeOf(current);
+
+            if (current === Object.prototype) {
+                break;
+            }
+        }
+
+        return layers;
+    } else {
+        // 不分层，合并所有键
+        const allKeys = new Set();
+        let current = o;
+
+        while (current != null) {
+            const ownKeys = Object.getOwnPropertyNames(current);
+            const ownSymbols = Object.getOwnPropertySymbols(current);
+
+            for (const key of [...ownKeys, ...ownSymbols]) {
+                allKeys.add(key);
+            }
+
+            current = Object.getPrototypeOf(current);
+
+            if (current === Object.prototype) {
+                break;
+            }
+        }
+
+        const keysArray = Array.from(allKeys);
+
+        if (enable_grouping) {
+            const grouped = {};
+
+            for (const key of keysArray) {
+                // Find descriptor in prototype chain
+                let desc = null;
+                let curr = o;
+                
+                while (curr != null) {
+                    desc = Object.getOwnPropertyDescriptor(curr, key);
+                    if (desc) break;
+                    curr = Object.getPrototypeOf(curr);
+                    if (curr === Object.prototype) break;
+                }
+                
+                if (desc) {
+                    const sig = get_prop_signature(key, desc);
+
+                    if (!grouped[sig]) {
+                        grouped[sig] = [];
+                    }
+                    grouped[sig].push(key);
+                }
+            }
+
+            return grouped;
+        } else {
+            return keysArray;
+        }
+    }
+};
+
+
+// nestify AND flatify is for creat test-samples
+
+const nestify = (o) => {
+    if (o == null) { 
+        return o;
+    }
+    
+    const keys = Object.keys(o);
+    
+    if (keys.length === 0) {
+        return {};
+    }
+    
+    if (keys.length === 1) {
+        return { [keys[0]]: o[keys[0]] };
+    }
+    
+    // 例如 o = {a:100, b:200}
+    // 第一个键放在最深的原型
+    let proto = { [keys[0]]: o[keys[0]] };
+    
+    // 中间的键，每个键一层
+    for (let i = 1; i < keys.length - 1; i++) {
+        const layer = { [keys[i]]: o[keys[i]] };
+        proto = Object.create(proto);
+        Object.assign(proto, layer);
+    }
+    
+    // 创建一个空的中间层 pr
+    const pr = Object.create(proto);
+    
+    // 创建最终对象，最后一个键放在自身
+    const newO = Object.create(pr);
+    newO[keys[keys.length - 1]] = o[keys[keys.length - 1]];
+    
+    return newO;
+};
+
+const flatify = (o) => {
+    if (o == null) { 
+        return o;
+    }
+    
+    const result = {};
+    let current = o;
+    
+    // 遍历整个原型链
+    while (current != null) {
+        // 获取当前层的自身属性
+        const ownKeys = Object.keys(current);
+        for (const key of ownKeys) {
+            // 只添加还未出现的属性（保留最近层的值）
+            if (!(key in result)) {
+                result[key] = current[key];
+            }
+        }
+        current = Object.getPrototypeOf(current);
+        
+        // 避免遍历到 Object.prototype
+        if (current === Object.prototype) {
+            break;
+        }
+    }
+    
+    return result;
+};
+
+module.exports = (o, key, only_own = false) => o != null && (only_own ? Object.hasOwn(o, key) : key in o);
+////除主函数外,其他函数只适合用在cli 和测试框架里,例如inspect 某个对象
+
+module.exports.slow   = slow;
+module.exports.exact  = exact;
+module.exports.nestify = nestify;
+module.exports.flatify = flatify;
+module.exports.get_proto_chain = get_proto_chain;
+module.exports.get_prop_descs  = get_prop_descs;
+module.exports.get_prop_signature = get_prop_signature;
+module.exports.get_all_keys       = get_all_keys;
+
+

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "nv-facutil-has",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": ""
+}