flattify 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { _ as Notation, c as FlattenOptions, g as Prettify, h as Option, m as IsUnion, p as IsAny, r as Split, s as Flatten } from "./path-types-D9d1uvNh.cjs";
1
+ import { _ as Notation, c as FlattenOptions, g as Prettify, h as Option, m as IsUnion, p as IsAny, r as Split, s as Flatten } from "./path-types-BjuDIcLg.cjs";
2
2
  //#region src/flatten/flatten.d.ts
3
3
  /**
4
4
  * Flattens a nested object (or array) into a single-level object whose keys are the paths to each value.
@@ -30,9 +30,19 @@ import { _ as Notation, c as FlattenOptions, g as Prettify, h as Option, m as Is
30
30
  * @throws {TypeError} If `input` is not a plain object or array, or on a circular reference when `circular` is `'throw'`.
31
31
  */
32
32
  export declare function flatten<T extends object>(input: T): Flatten<T>;
33
+ /**
34
+ * Flattens `input` with options: the keys of the result follow `delimiter`, `notation`, `maxDepth`...
35
+ *
36
+ * @example
37
+ * ```ts
38
+ * flatten({ db: { host: 'localhost' } }, { delimiter: '__' });
39
+ * // { db__host: 'localhost' }
40
+ * ```
41
+ */
33
42
  export declare function flatten<T extends object, const O extends FlattenOptions>(input: T, options: O): Flatten<T, O>;
34
43
  //#endregion
35
44
  //#region src/unflatten/types.d.ts
45
+ /** Options of `unflatten`. Each one also changes the inferred type of the result. */
36
46
  interface UnflattenOptions {
37
47
  /** Splits the keys into paths. Default: `'.'`. */
38
48
  delimiter?: string;
@@ -147,6 +157,16 @@ type UnflattenWith<T, C extends Context> = IsWide<C> extends true ? Record<strin
147
157
  * @throws {TypeError} If `input` is not a plain object, with `asArray` when a top-level key is not an array index, or with the `'pointer'` notation when a key does not start with `/`.
148
158
  */
149
159
  export declare function unflatten<T extends object>(input: T): Unflatten<T>;
160
+ /**
161
+ * Rebuilds a nested object from `input` with options: another `delimiter` or `notation`, `asArray` to get
162
+ * an array back, `overwrite`, `arrayLimit`...
163
+ *
164
+ * @example
165
+ * ```ts
166
+ * unflatten({ '0.id': 1, '1.id': 2 }, { asArray: true });
167
+ * // [{ id: 1 }, { id: 2 }]
168
+ * ```
169
+ */
150
170
  export declare function unflatten<T extends object, const O extends UnflattenOptions>(input: T, options: O): Unflatten<T, O>;
151
171
  //#endregion
152
172
  export type { Flatten, FlattenOptions, Notation, Prettify, Unflatten, UnflattenOptions };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { _ as Notation, c as FlattenOptions, g as Prettify, h as Option, m as IsUnion, p as IsAny, r as Split, s as Flatten } from "./path-types-D9d1uvNh.js";
1
+ import { _ as Notation, c as FlattenOptions, g as Prettify, h as Option, m as IsUnion, p as IsAny, r as Split, s as Flatten } from "./path-types-BjuDIcLg.js";
2
2
  //#region src/flatten/flatten.d.ts
3
3
  /**
4
4
  * Flattens a nested object (or array) into a single-level object whose keys are the paths to each value.
@@ -30,9 +30,19 @@ import { _ as Notation, c as FlattenOptions, g as Prettify, h as Option, m as Is
30
30
  * @throws {TypeError} If `input` is not a plain object or array, or on a circular reference when `circular` is `'throw'`.
31
31
  */
32
32
  export declare function flatten<T extends object>(input: T): Flatten<T>;
33
+ /**
34
+ * Flattens `input` with options: the keys of the result follow `delimiter`, `notation`, `maxDepth`...
35
+ *
36
+ * @example
37
+ * ```ts
38
+ * flatten({ db: { host: 'localhost' } }, { delimiter: '__' });
39
+ * // { db__host: 'localhost' }
40
+ * ```
41
+ */
33
42
  export declare function flatten<T extends object, const O extends FlattenOptions>(input: T, options: O): Flatten<T, O>;
34
43
  //#endregion
35
44
  //#region src/unflatten/types.d.ts
45
+ /** Options of `unflatten`. Each one also changes the inferred type of the result. */
36
46
  interface UnflattenOptions {
37
47
  /** Splits the keys into paths. Default: `'.'`. */
38
48
  delimiter?: string;
@@ -147,6 +157,16 @@ type UnflattenWith<T, C extends Context> = IsWide<C> extends true ? Record<strin
147
157
  * @throws {TypeError} If `input` is not a plain object, with `asArray` when a top-level key is not an array index, or with the `'pointer'` notation when a key does not start with `/`.
148
158
  */
149
159
  export declare function unflatten<T extends object>(input: T): Unflatten<T>;
160
+ /**
161
+ * Rebuilds a nested object from `input` with options: another `delimiter` or `notation`, `asArray` to get
162
+ * an array back, `overwrite`, `arrayLimit`...
163
+ *
164
+ * @example
165
+ * ```ts
166
+ * unflatten({ '0.id': 1, '1.id': 2 }, { asArray: true });
167
+ * // [{ id: 1 }, { id: 2 }]
168
+ * ```
169
+ */
150
170
  export declare function unflatten<T extends object, const O extends UnflattenOptions>(input: T, options: O): Unflatten<T, O>;
151
171
  //#endregion
152
172
  export type { Flatten, FlattenOptions, Notation, Prettify, Unflatten, UnflattenOptions };
@@ -36,6 +36,7 @@ type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K; }[
36
36
  type IsRequiredInAll<U, K extends PropertyKey> = [U extends unknown ? (K extends RequiredKeys<U> ? never : 1) : never] extends [never] ? true : false;
37
37
  //#endregion
38
38
  //#region src/flatten/types.d.ts
39
+ /** Options of `flatten`. Each one also changes the inferred keys of the result. */
39
40
  interface FlattenOptions {
40
41
  /** Joins the keys of a path. Default: `'.'`. */
41
42
  delimiter?: string;
@@ -36,6 +36,7 @@ type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K; }[
36
36
  type IsRequiredInAll<U, K extends PropertyKey> = [U extends unknown ? (K extends RequiredKeys<U> ? never : 1) : never] extends [never] ? true : false;
37
37
  //#endregion
38
38
  //#region src/flatten/types.d.ts
39
+ /** Options of `flatten`. Each one also changes the inferred keys of the result. */
39
40
  interface FlattenOptions {
40
41
  /** Joins the keys of a path. Default: `'.'`. */
41
42
  delimiter?: string;
package/dist/path.d.cts CHANGED
@@ -1,5 +1,6 @@
1
- import { _ as Notation, a as ContainersOf, c as FlattenOptions, d as TupleEntries, f as TypeDepthLimit, h as Option, i as Below, l as Join, m as IsUnion, n as Segments, o as Context, p as IsAny, s as Flatten, t as PathContext, u as Kind } from "./path-types-D9d1uvNh.cjs";
1
+ import { _ as Notation, a as ContainersOf, c as FlattenOptions, d as TupleEntries, f as TypeDepthLimit, h as Option, i as Below, l as Join, m as IsUnion, n as Segments, o as Context, p as IsAny, s as Flatten, t as PathContext, u as Kind } from "./path-types-BjuDIcLg.cjs";
2
2
  //#region src/path/types.d.ts
3
+ /** How the paths given to the `flattify/path` helpers are written. */
3
4
  interface PathOptions {
4
5
  /** Separates the keys of a path. Default: `'.'`. */
5
6
  delimiter?: string;
@@ -8,6 +9,7 @@ interface PathOptions {
8
9
  /** Reads `\` as an escape, so `'a\\.b'` is the single key `'a.b'`. Default: `true`. */
9
10
  escape?: boolean;
10
11
  }
12
+ /** Options of `set`: how the path is written, and what is created for missing keys. */
11
13
  interface SetOptions extends PathOptions {
12
14
  /** Creates objects only, never arrays, for missing keys along the path. Default: `false`. */
13
15
  object?: boolean;
@@ -73,7 +75,24 @@ type SetValue<T, P extends string, O extends PathOptions = {}> = IsAny<T> extend
73
75
  * ```
74
76
  */
75
77
  export declare function get<T extends object, P extends Path<T>>(obj: T, path: P): Get<T, P>;
78
+ /**
79
+ * Reads the value at `path`, written in another `delimiter` or `notation`.
80
+ *
81
+ * @example
82
+ * ```ts
83
+ * get(order, '/items/0/sku', { notation: 'pointer' }); // 'BOOK-1'
84
+ * ```
85
+ */
76
86
  export declare function get<T extends object, P extends Path<T, O>, const O extends PathOptions>(obj: T, path: P, options: O): Get<T, P, O>;
87
+ /**
88
+ * Reads the value at a path only known at runtime, such as one coming from user input: the result is
89
+ * `unknown`.
90
+ *
91
+ * @example
92
+ * ```ts
93
+ * const value = get(data, error.instancePath, { notation: 'pointer' }); // unknown
94
+ * ```
95
+ */
77
96
  export declare function get(obj: object, path: string, options?: PathOptions): unknown;
78
97
  /**
79
98
  * `true` when every key of `path` exists, even if the value there is `undefined`.
@@ -102,6 +121,15 @@ export declare function has<T extends object, O extends PathOptions = {}>(obj: T
102
121
  * ```
103
122
  */
104
123
  export declare function set<T extends object, P extends Path<T>>(obj: T, path: P, value: SetValue<T, P>): T;
124
+ /**
125
+ * Sets the value at `path`, written in another `delimiter` or `notation`, or with `object` and
126
+ * `arrayLimit` to choose what is created for missing keys.
127
+ *
128
+ * @example
129
+ * ```ts
130
+ * set(config, 'db__port', 6543, { delimiter: '__' });
131
+ * ```
132
+ */
105
133
  export declare function set<T extends object, P extends Path<T, O>, const O extends SetOptions>(obj: T, path: P, value: SetValue<T, P, O>, options: O): T;
106
134
  /**
107
135
  * Deletes the key at `path` and returns `true`, or `false` when there was nothing to delete. Array
@@ -124,6 +152,14 @@ export declare function del<T extends object, O extends PathOptions = {}>(obj: T
124
152
  * ```
125
153
  */
126
154
  export declare function paths<T extends object>(obj: T): Extract<keyof Flatten<T>, string>[];
155
+ /**
156
+ * The paths `flatten(obj, options)` produces, with the same options.
157
+ *
158
+ * @example
159
+ * ```ts
160
+ * paths({ user: { tags: ['admin'] } }, { notation: 'bracket' }); // ['user.tags[0]']
161
+ * ```
162
+ */
127
163
  export declare function paths<T extends object, const O extends FlattenOptions>(obj: T, options: O): Extract<keyof Flatten<T, O>, string>[];
128
164
  type ContextOf<O> = {
129
165
  delimiter: Option<O, "delimiter", ".">;
package/dist/path.d.ts CHANGED
@@ -1,5 +1,6 @@
1
- import { _ as Notation, a as ContainersOf, c as FlattenOptions, d as TupleEntries, f as TypeDepthLimit, h as Option, i as Below, l as Join, m as IsUnion, n as Segments, o as Context, p as IsAny, s as Flatten, t as PathContext, u as Kind } from "./path-types-D9d1uvNh.js";
1
+ import { _ as Notation, a as ContainersOf, c as FlattenOptions, d as TupleEntries, f as TypeDepthLimit, h as Option, i as Below, l as Join, m as IsUnion, n as Segments, o as Context, p as IsAny, s as Flatten, t as PathContext, u as Kind } from "./path-types-BjuDIcLg.js";
2
2
  //#region src/path/types.d.ts
3
+ /** How the paths given to the `flattify/path` helpers are written. */
3
4
  interface PathOptions {
4
5
  /** Separates the keys of a path. Default: `'.'`. */
5
6
  delimiter?: string;
@@ -8,6 +9,7 @@ interface PathOptions {
8
9
  /** Reads `\` as an escape, so `'a\\.b'` is the single key `'a.b'`. Default: `true`. */
9
10
  escape?: boolean;
10
11
  }
12
+ /** Options of `set`: how the path is written, and what is created for missing keys. */
11
13
  interface SetOptions extends PathOptions {
12
14
  /** Creates objects only, never arrays, for missing keys along the path. Default: `false`. */
13
15
  object?: boolean;
@@ -73,7 +75,24 @@ type SetValue<T, P extends string, O extends PathOptions = {}> = IsAny<T> extend
73
75
  * ```
74
76
  */
75
77
  export declare function get<T extends object, P extends Path<T>>(obj: T, path: P): Get<T, P>;
78
+ /**
79
+ * Reads the value at `path`, written in another `delimiter` or `notation`.
80
+ *
81
+ * @example
82
+ * ```ts
83
+ * get(order, '/items/0/sku', { notation: 'pointer' }); // 'BOOK-1'
84
+ * ```
85
+ */
76
86
  export declare function get<T extends object, P extends Path<T, O>, const O extends PathOptions>(obj: T, path: P, options: O): Get<T, P, O>;
87
+ /**
88
+ * Reads the value at a path only known at runtime, such as one coming from user input: the result is
89
+ * `unknown`.
90
+ *
91
+ * @example
92
+ * ```ts
93
+ * const value = get(data, error.instancePath, { notation: 'pointer' }); // unknown
94
+ * ```
95
+ */
77
96
  export declare function get(obj: object, path: string, options?: PathOptions): unknown;
78
97
  /**
79
98
  * `true` when every key of `path` exists, even if the value there is `undefined`.
@@ -102,6 +121,15 @@ export declare function has<T extends object, O extends PathOptions = {}>(obj: T
102
121
  * ```
103
122
  */
104
123
  export declare function set<T extends object, P extends Path<T>>(obj: T, path: P, value: SetValue<T, P>): T;
124
+ /**
125
+ * Sets the value at `path`, written in another `delimiter` or `notation`, or with `object` and
126
+ * `arrayLimit` to choose what is created for missing keys.
127
+ *
128
+ * @example
129
+ * ```ts
130
+ * set(config, 'db__port', 6543, { delimiter: '__' });
131
+ * ```
132
+ */
105
133
  export declare function set<T extends object, P extends Path<T, O>, const O extends SetOptions>(obj: T, path: P, value: SetValue<T, P, O>, options: O): T;
106
134
  /**
107
135
  * Deletes the key at `path` and returns `true`, or `false` when there was nothing to delete. Array
@@ -124,6 +152,14 @@ export declare function del<T extends object, O extends PathOptions = {}>(obj: T
124
152
  * ```
125
153
  */
126
154
  export declare function paths<T extends object>(obj: T): Extract<keyof Flatten<T>, string>[];
155
+ /**
156
+ * The paths `flatten(obj, options)` produces, with the same options.
157
+ *
158
+ * @example
159
+ * ```ts
160
+ * paths({ user: { tags: ['admin'] } }, { notation: 'bracket' }); // ['user.tags[0]']
161
+ * ```
162
+ */
127
163
  export declare function paths<T extends object, const O extends FlattenOptions>(obj: T, options: O): Extract<keyof Flatten<T, O>, string>[];
128
164
  type ContextOf<O> = {
129
165
  delimiter: Option<O, "delimiter", ".">;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flattify",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "description": "Flatten and unflatten nested objects without losing data: dates, nulls, empty objects and dotted keys survive the round trip. Typed paths, safe on untrusted input, zero dependencies.",
5
5
  "author": "Fernando Machado Bernardino <fernandombernardino@gmail.com>",
6
6
  "homepage": "https://github.com/NandoMB/flattify#readme",