From 218305fa91ffab9aace17aeb8fd3284b9ab57bee Mon Sep 17 00:00:00 2001 From: Fernando Machado Bernardino Date: Sat, 26 Sep 2026 02:57:57 -0300 Subject: [PATCH] docs: document every exported symbol JSDoc with examples for every overload of flatten, unflatten, get, set and paths, and for the options interfaces, which JSR counts as separate symbols (62% documented before, 100% now). --- .changeset/document-every-symbol.md | 5 +++++ src/flatten/flatten.ts | 9 ++++++++ src/flatten/types.ts | 1 + src/path/path.ts | 34 +++++++++++++++++++++++++++++ src/path/types.ts | 2 ++ src/unflatten/types.ts | 1 + src/unflatten/unflatten.ts | 10 +++++++++ 7 files changed, 62 insertions(+) create mode 100644 .changeset/document-every-symbol.md diff --git a/.changeset/document-every-symbol.md b/.changeset/document-every-symbol.md new file mode 100644 index 0000000..67643ed --- /dev/null +++ b/.changeset/document-every-symbol.md @@ -0,0 +1,5 @@ +--- +'flattify': patch +--- + +Document every exported symbol: the options interfaces (`FlattenOptions`, `UnflattenOptions`, `PathOptions`, `SetOptions`) and every overload of `flatten`, `unflatten`, `get`, `set` and `paths` now have JSDoc with examples, shown in editors and on JSR. diff --git a/src/flatten/flatten.ts b/src/flatten/flatten.ts index 264da3b..93a4798 100644 --- a/src/flatten/flatten.ts +++ b/src/flatten/flatten.ts @@ -52,6 +52,15 @@ function validateWalk(maxDepth: number, circular: string): void { * @throws {TypeError} If `input` is not a plain object or array, or on a circular reference when `circular` is `'throw'`. */ export function flatten(input: T): Flatten; +/** + * Flattens `input` with options: the keys of the result follow `delimiter`, `notation`, `maxDepth`... + * + * @example + * ```ts + * flatten({ db: { host: 'localhost' } }, { delimiter: '__' }); + * // { db__host: 'localhost' } + * ``` + */ export function flatten(input: T, options: O): Flatten; export function flatten(input: object, options: FlattenOptions = {}): Record { const { delimiter = '.', notation = 'dot', maxDepth = Infinity, safe = false, keepEmpty = true, escape = true, circular = 'throw', transformKey, preserve } = options; diff --git a/src/flatten/types.ts b/src/flatten/types.ts index 3406905..905d881 100644 --- a/src/flatten/types.ts +++ b/src/flatten/types.ts @@ -1,6 +1,7 @@ import type { Notation } from '../shared/notation.ts'; import type { IsAny, IsUnion, Leaf, MergeVariants, Option, Prettify, ReplaceAll, UnionToIntersection } from '../shared/types.ts'; +/** Options of `flatten`. Each one also changes the inferred keys of the result. */ export interface FlattenOptions { /** Joins the keys of a path. Default: `'.'`. */ delimiter?: string; diff --git a/src/path/path.ts b/src/path/path.ts index 6ce5eca..2c4a58c 100644 --- a/src/path/path.ts +++ b/src/path/path.ts @@ -55,7 +55,24 @@ function checkTarget(input: unknown, name: string): void { * ``` */ export function get>(obj: T, path: P): Get; +/** + * Reads the value at `path`, written in another `delimiter` or `notation`. + * + * @example + * ```ts + * get(order, '/items/0/sku', { notation: 'pointer' }); // 'BOOK-1' + * ``` + */ export function get, const O extends PathOptions>(obj: T, path: P, options: O): Get; +/** + * Reads the value at a path only known at runtime, such as one coming from user input: the result is + * `unknown`. + * + * @example + * ```ts + * const value = get(data, error.instancePath, { notation: 'pointer' }); // unknown + * ``` + */ export function get(obj: object, path: string, options?: PathOptions): unknown; export function get(obj: object, path: string, options: PathOptions = {}): unknown { checkTarget(obj, 'get'); @@ -106,6 +123,15 @@ export function has(obj: object, path: string, options: PathOptions = {}): boole * ``` */ export function set>(obj: T, path: P, value: SetValue): T; +/** + * Sets the value at `path`, written in another `delimiter` or `notation`, or with `object` and + * `arrayLimit` to choose what is created for missing keys. + * + * @example + * ```ts + * set(config, 'db__port', 6543, { delimiter: '__' }); + * ``` + */ export function set, const O extends SetOptions>(obj: T, path: P, value: SetValue, options: O): T; export function set(obj: object, path: string, value: unknown, options: SetOptions = {}): object { checkTarget(obj, 'set'); @@ -165,6 +191,14 @@ export function del(obj: object, path: string, options: PathOptions = {}): boole * ``` */ export function paths(obj: T): Extract, string>[]; +/** + * The paths `flatten(obj, options)` produces, with the same options. + * + * @example + * ```ts + * paths({ user: { tags: ['admin'] } }, { notation: 'bracket' }); // ['user.tags[0]'] + * ``` + */ export function paths(obj: T, options: O): Extract, string>[]; export function paths(obj: object, options: FlattenOptions = {}): string[] { return Object.keys(flatten(obj, options)); diff --git a/src/path/types.ts b/src/path/types.ts index b7bad11..4da50cf 100644 --- a/src/path/types.ts +++ b/src/path/types.ts @@ -3,6 +3,7 @@ import type { Notation } from '../shared/notation.ts'; import type { Segments } from '../shared/path-types.ts'; import type { IsAny, IsUnion, Option } from '../shared/types.ts'; +/** How the paths given to the `flattify/path` helpers are written. */ export interface PathOptions { /** Separates the keys of a path. Default: `'.'`. */ delimiter?: string; @@ -12,6 +13,7 @@ export interface PathOptions { escape?: boolean; } +/** Options of `set`: how the path is written, and what is created for missing keys. */ export interface SetOptions extends PathOptions { /** Creates objects only, never arrays, for missing keys along the path. Default: `false`. */ object?: boolean; diff --git a/src/unflatten/types.ts b/src/unflatten/types.ts index a27ba3f..ad52ba0 100644 --- a/src/unflatten/types.ts +++ b/src/unflatten/types.ts @@ -2,6 +2,7 @@ import type { Notation } from '../shared/notation.ts'; import type { Split } from '../shared/path-types.ts'; import type { IsAny, IsUnion, Option, Prettify } from '../shared/types.ts'; +/** Options of `unflatten`. Each one also changes the inferred type of the result. */ export interface UnflattenOptions { /** Splits the keys into paths. Default: `'.'`. */ delimiter?: string; diff --git a/src/unflatten/unflatten.ts b/src/unflatten/unflatten.ts index 81a2473..4b1be12 100644 --- a/src/unflatten/unflatten.ts +++ b/src/unflatten/unflatten.ts @@ -85,6 +85,16 @@ function restoreArrays(candidates: Candidate[], arrayLimit: number): void { * @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 `/`. */ export function unflatten(input: T): Unflatten; +/** + * Rebuilds a nested object from `input` with options: another `delimiter` or `notation`, `asArray` to get + * an array back, `overwrite`, `arrayLimit`... + * + * @example + * ```ts + * unflatten({ '0.id': 1, '1.id': 2 }, { asArray: true }); + * // [{ id: 1 }, { id: 2 }] + * ``` + */ export function unflatten(input: T, options: O): Unflatten; export function unflatten(input: object, options: UnflattenOptions = {}): Record | unknown[] { const { delimiter = '.', notation = 'dot', object = false, overwrite = false, escape = true, arrayLimit = 1000, asArray = false, transformKey } = options;