### SafeProxy: Error-Throwing Property Access in JavaScript

Source: https://context7.com/blackflux/object-lib/llms.txt

SafeProxy creates a JavaScript proxy that throws descriptive errors when accessing non-existent properties. It can also be configured with a callback function for custom fallback logic when properties are not found. This prevents silent failures and allows for controlled handling of missing data.

```javascript
import { SafeProxy } from 'object-lib';

// Basic error on undefined access
const obj = { a: { b: { c: 1 } } };
const proxy = SafeProxy(obj);

console.log(proxy.a.b.c); // 1

try {
  console.log(proxy.a.x.y);
} catch (err) {
  console.error(err.message); // "Property 'a.x' does not exist"
}

// Custom fallback with callback
const config = {
  server: { port: 3000 },
  database: {}
};
const safeConfig = SafeProxy(config, {
  cb: ({ key, value, found }) => {
    if (!found) {
      return `<Not Specified: ${key}>`;
    }
    return value;
  }
});

console.log(safeConfig.server.port); // 3000
console.log(safeConfig.database.host); // "<Not Specified: database.host>"
console.log(safeConfig.cache.ttl); // "<Not Specified: cache.ttl>"

// Conditional overrides
const data = { a: { b: { c: 'original' } } };
const customProxy = SafeProxy(data, {
  cb: ({ key, value, found }) => {
    if (key === 'a.b') return '<overridden>';
    if (!found) return { missingKey: key };
    return value;
  }
});

console.log(customProxy.a.b); // "<overridden>"
console.log(customProxy.x.y.z); // { missingKey: 'x.y.z' }

// Chaining with missing properties
const apiData = { user: { profile: { name: 'Alice' } } };
const safeApi = SafeProxy(apiData, {
  cb: ({ key, value, found }) => found ? value : { _missing: key }
});

console.log(safeApi.user.profile.name); // "Alice"
console.log(safeApi.user.settings.theme.color);
// { _missing: 'user.settings.theme.color' }

// Primitives pass through unchanged
const str = 'hello';
const strProxy = SafeProxy(str);
console.log(strProxy); // "hello"

```

--------------------------------

### Create Safe Proxy for Object Property Access

Source: https://github.com/blackflux/object-lib/blob/master/README.md

Creates a 'wrapper' proxy object that throws an error when a non-existent nested property is accessed, unlike standard JavaScript which returns 'undefined'. This helps in identifying and preventing accidental access to undefined properties. It has no external dependencies.

```javascript
import { SafeProxy } from 'object-lib';

const myObj = { a: 1 };
const safeObj = SafeProxy(myObj);

console.log(safeObj.a); // => 1
// console.log(safeObj.b); // Throws an error
```

--------------------------------

### Smart JSON Parsing for LLM Outputs

Source: https://github.com/blackflux/object-lib/blob/master/README.md

Parses potentially malformed JSON strings, commonly generated by Large Language Models (LLMs), into JavaScript objects. This utility handles cases where standard JSON.parse might fail due to minor syntax errors. It does not rely on external npm packages.

```javascript
import { jsonSmartParse } from 'object-lib';

const invalidJson = '{ "key": "value", }'; // Trailing comma
const parsedObject = jsonSmartParse(invalidJson);
// parsedObject will be { key: 'value' }
```

--------------------------------

### Render Template Object with Variables

Source: https://github.com/blackflux/object-lib/blob/master/README.md

Takes a template object and renders it by substituting variables. The rendering process creates a deep copy of the template object. It supports basic templating similar to Mustache but with some features yet to be implemented. The `variables()` method returns all unique variables in the template.

```javascript
import { Template } from 'object-lib';

const template = new Template({ greeting: 'Hello {{name}}!' });
const rendered = template.render({ name: 'World' });
// rendered => { greeting: 'Hello World!' }

const vars = template.variables();
// vars => [ 'name' ]
```

--------------------------------

### Deep Clone Object with Selective Needles

Source: https://github.com/blackflux/object-lib/blob/master/README.md

Performs a deep clone of an object. It allows specifying 'needles' to include or exclude specific fields from the clone. Fields targeted by needles are either created as references (inclusion) or removed entirely (exclusion). The 'object-scan' syntax is used for defining needles. It does not have external dependencies.

```javascript
import { clone } from 'object-lib';

const data = { a: {}, b: {}, c: {} };
const cloned = clone(data, ['b', '!c']);

console.log(cloned);
// => { a: {}, b: {} }
console.log(cloned.a !== data.a);
// => true
console.log(cloned.b === data.b);
// => true
```

--------------------------------

### Merge Objects with Custom Logic

Source: https://github.com/blackflux/object-lib/blob/master/README.md

Merges multiple objects into a single object, allowing for custom merging logic defined by paths. The `logic` object can map paths (using 'object-scan' syntax) to fields or functions. If a function is provided, it determines the merge identifier. This function is a class constructor.

```javascript
import { Merge } from 'object-lib';

Merge()(
  { children: [{ id: 1 }, { id: 2 }] },
  { children: [{ id: 2 }, { id: 3 }] }
);
// => { children: [ { id: 1 }, { id: 2 }, { id: 2 }, { id: 3 } ] }

Merge({ '**[*]': 'id' })(
  { children: [{ id: 1 }, { id: 2 }] },
  { children: [{ id: 2 }, { id: 3 }] }
);
// => { children: [ { id: 1 }, { id: 2 }, { id: 3 } ] }
```

--------------------------------

### Perform Intelligent Object Merging with object-lib's 'Merge'

Source: https://context7.com/blackflux/object-lib/llms.txt

The 'Merge' function from object-lib creates custom merge strategies for objects and arrays. It uses object-scan patterns to define how to combine elements, supporting deduplication by ID, custom aggregation functions, and complex nested merging.

```javascript
import { Merge } from 'object-lib';

// Default merge concatenates arrays
const merge1 = Merge();
const result1 = merge1(
  { children: [{ id: 1 }, { id: 2 }] },
  { children: [{ id: 2 }, { id: 3 }] }
);
console.log(result1);
// { children: [{ id: 1 }, { id: 2 }, { id: 2 }, { id: 3 }] }

// Merge by ID to deduplicate and combine
const merge2 = Merge({ '**[*]': 'id' });
const result2 = merge2(
  { children: [{ id: 1 }, { id: 2, name: 'Alice' }] },
  { children: [{ id: 2, age: 30 }, { id: 3 }] }
);
console.log(result2);
// { children: [{ id: 1 }, { id: 2, name: 'Alice', age: 30 }, { id: 3 }] }

// Merge by custom function
const merge3 = Merge({
  '[*]': (arr) => arr.reduce((sum, val) => sum + val, 0)
});
const result3 = merge3(
  [[1, 2, 3], [2, 4], [1, 2]],
  [[3, 3], [1, 5], [3, 2]]
);
console.log(result3);
// [[1, 2, 3, 2, 4, 3, 3, 1, 5], [1, 2], [3, 2]]
// Arrays with sum=6 are merged together

// Complex nested merge with multiple patterns
const merge4 = Merge({
  '[*]': 'id',
  '[*].addresses[*]': 'type'
});
const users1 = [
  { id: 1, name: 'Alice', addresses: [{ type: 'home', city: 'NYC' }] }
];
const users2 = [
  { id: 1, addresses: [{ type: 'work', city: 'SF' }, { type: 'home', zip: '10001' }] },
  { id: 2, name: 'Bob' }
];
const result4 = merge4(users1, users2);
console.log(result4);
// [
//   {
//     id: 1,
//     name: 'Alice',
//     addresses: [
//       { type: 'home', city: 'NYC', zip: '10001' },
//       { type: 'work', city: 'SF' }
//     ]
//   },
//   { id: 2, name: 'Bob' }
// ]

// Merge multiple objects
const merge5 = Merge({ '[*]': 'key' });
const result5 = merge5(
  [{ key: 'a', value: 1 }],
  [{ key: 'b', value: 2 }],
  [{ key: 'a', extra: 'data' }]
);
console.log(result5);
// [{ key: 'a', value: 1, extra: 'data' }, { key: 'b', value: 2 }]
```

--------------------------------

### Template: Variable Substitution in JavaScript Objects

Source: https://context7.com/blackflux/object-lib/llms.txt

The Template utility processes an object structure, identifying and substituting variables. It supports direct variable names and mustache-style template strings (e.g., `{{variable}}`). Unresolved variables remain in their original template string format after rendering.

```javascript
import { Template } from 'object-lib';

// Basic variable substitution
const template1 = Template({
  greeting: 'userName'
});
console.log(template1.variables()); // ['userName']
console.log(template1.render({ userName: 'Alice' }));
// { greeting: 'Alice' }

// Mustache-style templates
const template2 = Template({
  message: 'Hello {{name}}, you have {{count}} notifications',
  user: {
    fullName: '{{firstName}} {{lastName}}'
  }
});
console.log(template2.variables());
// ['name', 'count', 'firstName', 'lastName']

console.log(template2.render({
  name: 'Alice',
  count: 5,
  firstName: 'Alice',
  lastName: 'Smith'
}));
// {
//   message: 'Hello Alice, you have 5 notifications',
//   user: { fullName: 'Alice Smith' }
// }

// Complex nested template
const emailTemplate = Template({
  to: 'recipientEmail',
  subject: 'Welcome {{userName}}!',
  body: {
    greeting: 'Dear {{userName}}',
    content: 'Your account {{accountId}} is now active.',
    footer: 'Sent on {{date}}'
  },
  metadata: {
    template: 'welcome-email',
    version: 'templateVersion'
  }
});

console.log(emailTemplate.variables());
// ['recipientEmail', 'userName', 'accountId', 'date', 'templateVersion']

const rendered = emailTemplate.render({
  recipientEmail: 'alice@example.com',
  userName: 'Alice',
  accountId: 'ACC123',
  date: '2024-01-15',
  templateVersion: '1.0'
});

console.log(rendered);
// {
//   to: 'alice@example.com',
//   subject: 'Welcome Alice!',
//   body: {
//     greeting: 'Dear Alice',
//     content: 'Your account ACC123 is now active.',
//     footer: 'Sent on 2024-01-15'
//   },
//   metadata: {
//     template: 'welcome-email',
//     version: '1.0'
//   }
// }

// Partial rendering with missing variables
const partial = Template({
  available: '{{varA}}',
  missing: '{{varB}}'
});
const result = partial.render({ varA: 'provided' });
console.log(result);
// { available: 'provided', missing: '{{varB}}' }
// Missing variables remain as template strings

```

--------------------------------

### Align Object Keys Recursively with Reference Structure (JavaScript)

Source: https://context7.com/blackflux/object-lib/llms.txt

The `align` function recursively reorders the keys of a target object to match the structure of a reference object. It preserves all values and handles nested objects. Keys not present in the reference are appended at the end.

```javascript
import { align } from 'object-lib';

// Basic key reordering
const obj = { k1: 1, k2: 2 };
const ref = { k2: null, k1: null };
align(obj, ref);
console.log(obj); // { k2: 2, k1: 1 }

// Recursive alignment with nested objects
const config = {
  database: { host: 'localhost', port: 5432, user: 'admin' },
  server: { port: 3000, host: '0.0.0.0' }
};
const template = {
  server: { host: null, port: null },
  database: { user: null, host: null, port: null }
};
align(config, template);
console.log(config);
// {
//   server: { host: '0.0.0.0', port: 3000 },
//   database: { user: 'admin', host: 'localhost', port: 5432 }
// }

// Keys not in reference are appended at the end
const data = { key3: 'c', key2: 'b', key1: 'a' };
const order = { key1: null };
align(data, order);
console.log(data); // { key1: 'a', key3: 'c', key2: 'b' }
```

--------------------------------

### Selective Deep Cloning with Reference Preservation (JavaScript)

Source: https://context7.com/blackflux/object-lib/llms.txt

The `clone` function creates a deep copy of an object, allowing selective preservation of references using object-scan needle syntax. This provides granular control over which nested objects or arrays are cloned and which remain as references to the original.

```javascript
import { clone } from 'object-lib';

// Deep clone with specific references
const data = {
  userConfig: { theme: 'dark' },
  sharedCache: { data: [1, 2, 3] },
  tempData: { value: 42 }
};
const cloned = clone(data, ['sharedCache']);

console.log(cloned !== data); // true
console.log(cloned.userConfig !== data.userConfig); // true (deep cloned)
console.log(cloned.sharedCache === data.sharedCache); // true (reference preserved)

// Shallow clone using '**' needle
const original = { a: { b: { c: 1 } } };
const shallow = clone(original, ['**']);
console.log(shallow !== original); // true
console.log(shallow.a === original.a); // true (all nested objects are references)

// Exclude fields with '!' prefix
const fullData = {
  publicInfo: { name: 'John' },
  privateInfo: { ssn: '123-45-6789' },
  metadata: { created: '2024-01-01' }
};
const sanitized = clone(fullData, ['!privateInfo']);
console.log(sanitized);
// { publicInfo: { name: 'John' }, metadata: { created: '2024-01-01' } }

// Complex selective cloning
const complex = {
  user: { id: 1, name: 'Alice' },
  posts: [
    { id: 1, content: 'Hello' },
    { id: 2, content: 'World' }
  ]
};
const result = clone(complex, ['posts[0]', '!user.name']);
console.log(result);
// { user: { id: 1 }, posts: [{ id: 1, content: 'Hello' }, { id: 2, content: 'World' }] }
console.log(result.posts[0] === complex.posts[0]); // true (reference)
console.log(result.posts[1] !== complex.posts[1]); // true (deep cloned)
```

--------------------------------

### Align Object Order Recursively with Reference

Source: https://github.com/blackflux/object-lib/blob/master/README.md

Aligns the ordering of properties in a target object to match a reference object recursively. This function modifies the target object in place. It does not have external dependencies beyond the object-lib library itself.

```javascript
import { align } from 'object-lib';

const obj = { k1: 1, k2: 2 };
const ref = { k2: null, k1: null };

align(obj, ref);
// obj => { k2: 1, k1: 2 }
```

--------------------------------

### Parse Malformed JSON with object-lib's 'jsonSmartParse'

Source: https://context7.com/blackflux/object-lib/llms.txt

The 'jsonSmartParse' function safely parses JSON strings, even those containing common LLM-generated issues like markdown code blocks or unescaped special characters (newlines, tabs). It handles various input formats, including standard JSON strings and JSON embedded within markdown.

```javascript
import { jsonSmartParse } from 'object-lib';

// Parse JSON wrapped in markdown code blocks
const markdown = ````json
{
  "name": "John",
  "age": 30
}
``` `;
const result1 = jsonSmartParse(markdown);
console.log(result1); // { name: 'John', age: 30 }

// Handle unescaped special characters in strings
const malformed = `{
  "message": "Line 1
Line 2\tTabbed
End"
}`;
const result2 = jsonSmartParse(malformed);
console.log(result2); // { message: 'Line 1\nLine 2\tTabbed\rEnd' }

// Parse JSON without code block markers
const normal = '{"valid": true}';
const result3 = jsonSmartParse(normal);
console.log(result3); // { valid: true }

// Real-world LLM output handling
const llmOutput = `Here's the data:
```
{
  "status": "ok",
  "description": "First line
Second line",
  "count": 42
}
``` `;
const parsed = jsonSmartParse(llmOutput);
console.log(parsed);
// { status: 'ok', description: 'First line\nSecond line', count: 42 }
```

--------------------------------

### Check Recursive Object Containment with object-lib's 'contains'

Source: https://context7.com/blackflux/object-lib/llms.txt

The 'contains' function checks if a subtree is recursively contained within a larger tree. It performs deep comparisons of types, array lengths, object keys, and values. It returns false if there's a type mismatch.

```javascript
import { contains } from 'object-lib';

// Basic object containment
const tree = { a: [1, 2], b: 'c', d: { e: 3 } };
const subtree1 = { a: [1, 2] };
console.log(contains(tree, subtree1)); // true

// Array length must match exactly
const subtree2 = { a: [1] };
console.log(contains(tree, subtree2)); // false

// Subset of keys is valid
const subtree3 = { b: 'c' };
console.log(contains(tree, subtree3)); // true

// Nested containment check
const apiResponse = {
  status: 'success',
  data: {
    users: [
      { id: 1, name: 'Alice', role: 'admin' },
      { id: 2, name: 'Bob', role: 'user' }
    ]
  },
  metadata: { timestamp: 1234567890 }
};

const expectedStructure = {
  status: 'success',
  data: {
    users: [
      { id: 1, name: 'Alice' },
      { id: 2, name: 'Bob' }
    ]
  }
};

console.log(contains(apiResponse, expectedStructure)); // true

// Type mismatch returns false
console.log(contains({ value: 42 }, { value: '42' })); // false
```

--------------------------------

### Check Object Containment Recursively

Source: https://github.com/blackflux/object-lib/blob/master/README.md

Recursively checks if a `subtree` object is contained within a `tree` object. Different types are not considered contained. Arrays are contained if they have the same length and corresponding elements are contained. Objects are contained if their keys are a subset and respective values are contained. Other types are contained if they match exactly. It has no external dependencies.

```javascript
import { contains } from 'object-lib';

contains({ a: [1, 2], b: 'c' }, { a: [1, 2] });
// => true

contains({ a: [1, 2], b: 'c' }, { a: [1] });
// => false
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.