Merge pull request #10 from panates/dev

Dev

Author: erayhanoglu

CHANGELOG.md

@@ -1,7 +1,11 @@
 ## Changelog
 
-### [v2.1.1](https://github.com/panates/jsopen-objects/compare/v2.1.0...v2.1.1) - 
+### [v2.2.0](https://github.com/panates/jsopen-objects/compare/v2.1.1...v2.2.0) - 
 
 #### 🪲 Fixes
 
-- fix: Fixed "keepExisting" with "deep" option do not overwrite existing @Eray Hanoğlu 
+- fix: Fixed array merge issue @Eray Hanoğlu 
+
+#### 💬 General Changes
+
+- doc: Added documentation @Eray Hanoğlu 

README.md

@@ -7,6 +7,24 @@
 
 A 'swiss army knife' solution for working with javascript objects.
 
+## Functions
+
+### [merge](docs/merge.md)
+Is a powerful, flexible tool for merging objects, arrays, and their nested properties.
+
+### [clone / deepClone](docs/clone.md)
+Easy ways to create shallow or deep copies of objects and arrays.
+
+### [omit / omitUndefined / omitNull / omitNullish](docs/omit.md)
+Easily exclude specific keys or nullish values from objects.
+
+### [updateErrorMessage](docs/update-error-message.md)
+Update an Error object's message while correctly refreshing the stack trace.
+
+### [Utilities](docs/utils.md)
+Various utility functions for object and type checking.
+
+
 ## Installation
 
 `$ npm install @jsopen/objects`

docs/clone.md

@@ -0,0 +1,81 @@
+# clone / deepClone
+
+The `clone` and `deepClone` functions provide easy ways to create copies of objects and arrays. They are built on top of the [`merge`](merge.md) function and support all its powerful options.
+
+## Functions
+
+### `clone(obj, options?)`
+
+Creates a copy of the given object. By default, it performs a **deep clone** of plain objects and arrays.
+
+- **Default behavior**: Unlike `merge`, `clone` sets `deep: true` by default.
+- **Plain Objects/Arrays**: Recursively clones nested plain objects and arrays.
+- **Class Instances**: Non-plain objects (class instances) are copied by reference unless `deep: 'full'` is passed in options.
+
+```typescript
+import { clone } from '@jsopen/objects';
+
+const original = { a: 1, b: { c: 2 } };
+const copy = clone(original);
+
+copy.b.c = 3;
+console.log(original.b.c); // 2 (original is unchanged)
+```
+
+### `deepClone(obj, options?)`
+
+Creates a **full deep copy** of the given object, including class instances.
+
+- **Behavior**: Sets `deep: 'full'` by default.
+- **All Objects**: Recursively clones all objects, including class instances (excluding built-in types like `Date`, `RegExp`, etc.).
+
+```typescript
+import { deepClone } from '@jsopen/objects';
+
+class MyClass {
+  value = 1;
+}
+
+const original = { obj: new MyClass() };
+const copy = deepClone(original);
+
+copy.obj.value = 2;
+console.log(original.obj.value); // 1 (instance was cloned)
+```
+
+## Options
+
+Both functions accept the same options as the [`merge`](merge.md) function (except `deepClone` which forces `deep: 'full'`).
+
+| Option            | Type                                | Default | Description                                                                           |
+|:------------------|:------------------------------------|:--------|:--------------------------------------------------------------------------------------|
+| `deep`            | `boolean \| 'full' \| CallbackFn`   | `true`* | Enables deep cloning. (`true` for `clone`, `'full'` for `deepClone`)                  |
+| `copyDescriptors` | `boolean`                           | `false` | If true, copies property descriptors (getters, setters, etc.).                        |
+| `symbolKeys`      | `boolean`                           | `true`  | Whether to include properties with Symbol keys.                                       |
+| `ignoreUndefined` | `boolean`                           | `true`  | If true, `undefined` values will be ignored.                                          |
+| `ignoreNulls`     | `boolean`                           | `false` | If true, `null` values will be ignored.                                               |
+| `filter`          | `CallbackFn`                        | -       | Callback to exclude properties from being cloned.                                     |
+
+*\*Note: In `clone`, the default for `deep` is `true`. In `deepClone`, it is fixed to `'full'`.*
+
+## Usage Examples
+
+### Cloning with Filtering
+
+```typescript
+const original = { a: 1, secret: '123' };
+const copy = clone(original, {
+  filter: (val, { key }) => key !== 'secret'
+});
+// copy is { a: 1 }
+```
+
+### Preserving Property Descriptors
+
+```typescript
+const original = {
+  get id() { return Math.random(); }
+};
+const copy = clone(original, { copyDescriptors: true });
+// copy now has the 'id' getter.
+```

docs/merge.md

@@ -0,0 +1,144 @@
+# merge
+
+The `merge` function is a powerful, flexible tool for merging objects, arrays, and their nested properties.
+It supports deep merging, merging multiple sources, property descriptor cloning, array merging strategies,
+and custom filtering logic.
+
+## Features
+
+- **Deep Merging**: Option to deeply merge objects and arrays.
+- **Multiple Sources**: Merge an array of objects into a target object.
+- **Merge Arrays**: Choose between overwriting, appending, or merging unique array elements.
+- **Property Descriptors**: Clone getter/setter and other property descriptors.
+- **Custom Filters**: Exclude specific properties based on custom logic.
+- **Security**: Built-in protection against prototype pollution (`__proto__`, `constructor`).
+- **TypeScript Ready**: Full type safety and intelligent merging of source types.
+
+## Basic Usage
+
+```typescript
+import { merge } from '@jsopen/objects';
+
+const target = { a: 1, b: 2 };
+const source = { b: 3, c: 4 };
+
+merge(target, source);
+// target is now: { a: 1, b: 3, c: 4 }
+```
+
+### Merging Multiple Sources
+
+```typescript
+const target = { a: 1 };
+const sources = [{ b: 2 }, { c: 3 }];
+
+merge(target, sources);
+// target is now: { a: 1, b: 2, c: 3 }
+```
+
+## Options
+
+The `merge` function accepts an optional `Options` object as its third argument.
+
+| Option            | Type                                | Default | Description                                                                           |
+|:------------------|:------------------------------------|:--------|:--------------------------------------------------------------------------------------|
+| `deep`            | `boolean \| 'full' \| CallbackFn`   | `false` | Enables deep merging. `true` only for plain objects/arrays, `'full'` for all objects. |
+| `mergeArrays`     | `boolean \| 'unique' \| CallbackFn` | `false` | Controls how arrays are merged.                                                       |
+| `keepExisting`    | `boolean \| CallbackFn`             | `false` | If true, does not overwrite existing properties in the target.                        |
+| `copyDescriptors` | `boolean`                           | `false` | If true, copies property descriptors (getters, setters, etc.).                        |
+| `symbolKeys`      | `boolean`                           | `true`  | Whether to include properties with Symbol keys.                                       |
+| `ignoreUndefined` | `boolean`                           | `true`  | If true, `undefined` values in source will be ignored.                                |
+| `ignoreNulls`     | `boolean`                           | `false` | If true, `null` values in source will be ignored.                                     |
+| `ignoreSource`    | `CallbackFn`                        | -       | Callback to ignore specific source values.                                            |
+| `filter`          | `CallbackFn`                        | -       | Callback to exclude properties from both target and source.                           |
+
+### Deep Merging
+
+- `true`: Merges plain objects and arrays recursively. Non-plain objects (class instances) are assigned by reference.
+- `'full'`: Merges all objects including class instances (excluding built-in types like `Date`, `RegExp`, etc.).
+- `CallbackFn`: A function `(value, context) => boolean` to decide whether to go deep for a specific path.
+
+```typescript
+merge(target, source, { deep: true });
+
+// Using a callback to deep merge only specific paths
+merge(target, source, {
+  deep: (val, { path }) => path.startsWith('metadata')
+});
+```
+
+### Array Merging
+
+- `true`: Appends source array elements to the target array.
+- `'unique'`: Appends source array elements and ensures the resulting array has unique values.
+- `CallbackFn`: A function `(value, context) => boolean` to decide whether to merge arrays for a specific path.
+
+```typescript
+const target = { tags: ['js'] };
+const source = { tags: ['ts', 'js'] };
+
+merge(target, source, { mergeArrays: 'unique' });
+// target.tags is now: ['js', 'ts']
+```
+
+### Property Descriptors
+
+By default, `merge` copies values. Enable `copyDescriptors` to preserve getters, setters, and other attributes.
+
+```typescript
+const source = {
+  get id() {
+    return Math.random();
+  }
+};
+
+merge(target, source, { copyDescriptors: true });
+// target now has the 'id' getter, not just a static value.
+```
+
+### Filtering and Ignoring
+
+```typescript
+merge(target, source, {
+  // Ignore source values that are booleans
+  ignoreSource: (val) => typeof val === 'boolean',
+
+  // Ignore specific keys
+  filter: (val, { key }) => key !== 'internalSecret',
+
+  // Keep target's value if it already exists
+  keepExisting: true
+});
+```
+
+## Security
+
+The function automatically skips keys that could lead to prototype pollution:
+
+- `__proto__`
+- `constructor`
+
+## Type Definitions
+
+```typescript
+type CallbackFn = (value: any, ctx: CallbackContext) => boolean;
+
+interface CallbackContext {
+  source: any;
+  target: any;
+  key: string | symbol | number;
+  path: string; // Dot-separated path, e.g., "user.profile.id"
+}
+
+interface Options {
+  deep?: boolean | 'full' | CallbackFn;
+  symbolKeys?: boolean;
+  mergeArrays?: boolean | 'unique' | CallbackFn;
+  keepExisting?: boolean | CallbackFn;
+  copyDescriptors?: boolean;
+  ignoreSource?: CallbackFn;
+  ignoreUndefined?: boolean;
+  ignoreNulls?: boolean;
+  filter?: CallbackFn;
+}
+```

docs/omit.md

@@ -0,0 +1,69 @@
+# omit / omitUndefined / omitNull / omitNullish
+
+These functions provide convenient ways to exclude specific properties, `undefined` values, or `null` values from an object. They are built on top of the [`merge`](merge.md) function.
+
+## Functions
+
+### `omit(obj, keys)`
+
+Creates a new object that includes all properties of `obj` except the specified `keys`. This is a shallow operation.
+
+```typescript
+import { omit } from '@jsopen/objects';
+
+const original = { a: 1, b: 2, c: 3 };
+const result = omit(original, ['b', 'c']);
+// result is { a: 1 }
+```
+
+### `omitUndefined(obj, deep?)`
+
+Creates a new object by excluding all properties that have `undefined` as their value.
+
+- `deep: false` (default): Only top-level `undefined` values are removed.
+- `deep: true`: Recursively removes `undefined` values from plain objects and arrays.
+- `deep: 'full'`: Recursively removes `undefined` values from all objects including class instances.
+
+```typescript
+import { omitUndefined } from '@jsopen/objects';
+
+const original = { a: 1, b: undefined, c: { d: undefined } };
+const result = omitUndefined(original, true);
+// result is { a: 1, c: {} }
+```
+
+### `omitNull(obj, deep?)`
+
+Creates a new object by excluding all properties that have `null` as their value.
+
+- `deep: false` (default): Only top-level `null` values are removed.
+- `deep: true`: Recursively removes `null` values from plain objects and arrays.
+- `deep: 'full'`: Recursively removes `null` values from all objects including class instances.
+
+```typescript
+import { omitNull } from '@jsopen/objects';
+
+const original = { a: 1, b: null, c: { d: null } };
+const result = omitNull(original, true);
+// result is { a: 1, c: {} }
+```
+
+### `omitNullish(obj, deep?)`
+
+Creates a new object by excluding all properties that have either `null` or `undefined` as their value.
+
+- `deep: false` (default): Only top-level nullish values are removed.
+- `deep: true`: Recursively removes nullish values from plain objects and arrays.
+- `deep: 'full'`: Recursively removes nullish values from all objects including class instances.
+
+```typescript
+import { omitNullish } from '@jsopen/objects';
+
+const original = { a: 1, b: null, c: undefined, d: { e: null } };
+const result = omitNullish(original, true);
+// result is { a: 1, d: {} }
+```
+
+## Options
+
+These functions use standard [`merge`](merge.md) options internally. `omitUndefined`, `omitNull`, and `omitNullish` preserve property descriptors by default (`copyDescriptors: true`).

docs/update-error-message.md

@@ -0,0 +1,26 @@
+# updateErrorMessage
+
+The `updateErrorMessage` function updates an `Error` object's message and refreshes its stack trace to reflect the point where the update occurred.
+
+## Function
+
+### `updateErrorMessage(err, newMessage)`
+
+Updates the message of the error and captures a new stack trace.
+
+- **V8 Engines (Node.js, Chrome)**: Uses `Error.captureStackTrace` for optimal performance and accuracy.
+- **Other Engines**: Provides a fallback mechanism that manually reconstructs the stack trace with the new message while preserving original stack frames.
+
+```typescript
+import { updateErrorMessage } from '@jsopen/objects';
+
+const err = new Error('Original message');
+updateErrorMessage(err, 'Updated message');
+
+console.log(err.message); // "Updated message"
+console.log(err.stack);   // Stack trace starting with "Error: Updated message"
+```
+
+## Why use this?
+
+When re-throwing or wrapping errors, simply changing `err.message` might not update the first line of `err.stack` in some environments, or you might want the stack trace to point to the location where the error was "enhanced" rather than where it was originally created. `updateErrorMessage` ensures consistency across different JavaScript engines.