docs: document every exported symbol

.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.

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<T extends object>(input: T): Flatten<T>;
+/**
+ * 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<T extends object, const O extends FlattenOptions>(input: T, options: O): Flatten<T, O>;
 export function flatten(input: object, options: FlattenOptions = {}): Record<string, unknown> {
   const { delimiter = '.', notation = 'dot', maxDepth = Infinity, safe = false, keepEmpty = true, escape = true, circular = 'throw', transformKey, preserve } = options;

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;

src/path/path.ts

@@ -55,7 +55,24 @@ function checkTarget(input: unknown, name: string): void {
  * ```
  */
 export function get<T extends object, P extends Path<T>>(obj: T, path: P): Get<T, P>;
+/**
+ * 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<T extends object, P extends Path<T, O>, const O extends PathOptions>(obj: T, path: P, options: O): Get<T, P, O>;
+/**
+ * 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<T extends object, P extends Path<T>>(obj: T, path: P, value: SetValue<T, P>): 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<T extends object, P extends Path<T, O>, const O extends SetOptions>(obj: T, path: P, value: SetValue<T, P, O>, 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<T extends object>(obj: T): Extract<keyof Flatten<T>, 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<T extends object, const O extends FlattenOptions>(obj: T, options: O): Extract<keyof Flatten<T, O>, string>[];
 export function paths(obj: object, options: FlattenOptions = {}): string[] {
   return Object.keys(flatten(obj, options));

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;

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;

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<T extends object>(input: T): Unflatten<T>;
+/**
+ * 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<T extends object, const O extends UnflattenOptions>(input: T, options: O): Unflatten<T, O>;
 export function unflatten(input: object, options: UnflattenOptions = {}): Record<string, unknown> | unknown[] {
   const { delimiter = '.', notation = 'dot', object = false, overwrite = false, escape = true, arrayLimit = 1000, asArray = false, transformKey } = options;