Updated docs and typings.

Author: uhop

README.md

@@ -40,6 +40,31 @@ pipeline.on('data', ({value}) => {
 pipeline.on('end', () => console.log(byDepartment));
 ```
 
+This works because `pick` selected a single array — `streamArray` then streams its elements. When `pick` matches **several** subobjects, its output is a sequence of separate sub-trees — structurally the same token stream a [JSON Streaming](https://en.wikipedia.org/wiki/JSON_Streaming) source produces — and [streamValues()](https://github.com/uhop/stream-json/wiki/StreamValues) assembles each match into its own object:
+
+```js
+import {parser} from 'stream-json';
+import {pick} from 'stream-json/filters/pick.js';
+import {streamValues} from 'stream-json/streamers/stream-values.js';
+import chain from 'stream-chain';
+import fs from 'node:fs';
+
+// depts.json: {"departments": [
+//   {"name": "dev", "head": {"name": "Alice", "id": 1}, "staff": 20},
+//   {"name": "ops", "head": {"name": "Bob", "id": 2}, "staff": 10}
+// ]}
+const pipeline = chain([
+  fs.createReadStream('depts.json'),
+  parser(),
+  pick({filter: /^departments\.\d+\.head\b/}), // every department's "head" subobject
+  streamValues() // assemble each picked sub-tree
+]);
+
+pipeline.on('data', ({value}) => console.log(value.name));
+// → Alice
+// → Bob
+```
+
 Each stage is a building block; `stream-chain` wires them into one stream and handles the streaming and backpressure. To read straight from a file you can drop `createReadStream` and use the Node-only [parseFile()](https://github.com/uhop/stream-json/wiki/parseFile); to write a stream back to disk, use [stringerToFile()](https://github.com/uhop/stream-json/wiki/stringerToFile). See [Recipes](https://github.com/uhop/stream-json/wiki/Recipes) for more.
 
 ## Installation

src/core/filters/filter-base.d.ts

@@ -1,4 +1,4 @@
-import {Flushable, Many, none} from 'stream-chain/defs.js';
+import {Many, none} from 'stream-chain/defs.js';
 import parser from '../parser.js';
 
 /**
@@ -10,9 +10,7 @@ import parser from '../parser.js';
  * @param config - Internal configuration defining filter behavior (actions, transitions).
  * @returns A factory that takes user-facing options and returns a flushable filter function.
  */
-declare function filterBase(
-  config?: filterBase.FilterBaseConfig
-): (options?: filterBase.FilterBaseOptions) => Flushable<parser.Token, parser.Token | Many<parser.Token> | typeof none>;
+declare function filterBase(config?: filterBase.FilterBaseConfig): (options?: filterBase.FilterBaseOptions) => parser.TokenTransform;
 
 declare namespace filterBase {
   /** User-facing options shared by all filters. */

src/core/filters/filter.d.ts

@@ -12,7 +12,7 @@ import filterBase from './filter-base.js';
  *
  * @param options - Filter options including `acceptObjects`.
  */
-declare function filter(options?: filter.FilterOptions): Flushable<parser.Token, parser.Token | Many<parser.Token> | typeof none>;
+declare function filter(options?: filter.FilterOptions): parser.TokenTransform;
 
 declare namespace filter {
   /** Options for `filter`, extending filter base options. */

src/core/filters/ignore.d.ts

@@ -12,7 +12,7 @@ import filterBase from './filter-base.js';
  *
  * @param options - Filter options (`filter`, `once`, `pathSeparator`).
  */
-declare function ignore(options?: filterBase.FilterBaseOptions): Flushable<parser.Token, parser.Token | Many<parser.Token> | typeof none>;
+declare function ignore(options?: filterBase.FilterBaseOptions): parser.TokenTransform;
 
 declare namespace ignore {
   /** Creates a `parser() + ignore()` pipeline as a flushable function. */

src/core/filters/pick.d.ts

@@ -12,7 +12,7 @@ import filterBase from './filter-base.js';
  *
  * @param options - Filter options (`filter`, `once`, `pathSeparator`).
  */
-declare function pick(options?: filterBase.FilterBaseOptions): Flushable<parser.Token, parser.Token | Many<parser.Token> | typeof none>;
+declare function pick(options?: filterBase.FilterBaseOptions): parser.TokenTransform;
 
 declare namespace pick {
   /** Creates a `parser() + pick()` pipeline as a flushable function. */

src/core/filters/replace.d.ts

@@ -12,7 +12,7 @@ import filterBase from './filter-base.js';
  *
  * @param options - Filter and replacement options.
  */
-declare function replace(options?: replace.ReplaceOptions): Flushable<parser.Token, parser.Token | Many<parser.Token> | typeof none>;
+declare function replace(options?: replace.ReplaceOptions): parser.TokenTransform;
 
 declare namespace replace {
   /** Options for `replace`, extending filter base options with a replacement value. */

src/core/parser.d.ts

@@ -14,7 +14,7 @@ import {Flushable, Many, none} from 'stream-chain/defs.js';
  * @param options - Parser configuration including packing, streaming, and JSON streaming options.
  * @returns A flushable function for use in a `chain()` pipeline.
  */
-declare function parser(options?: parser.ParserOptions): Flushable<string, Many<parser.Token> | typeof none>;
+declare function parser(options?: parser.ParserOptions): parser.TokenSource;
 
 declare namespace parser {
   /**
@@ -70,14 +70,27 @@ declare namespace parser {
     jsonStreaming?: boolean;
   }
 
+  /** Stage shape of the parser: `text` → `tokens`. */
+  export type TokenSource = Flushable<string, Many<Token> | typeof none>;
+  /** Stage shape of the filters: `tokens` → `tokens`. */
+  export type TokenTransform = Flushable<Token, Token | Many<Token> | typeof none>;
+  /** Stage shape of the streamers: `tokens` → items (see `KeyedValue` in `streamers/stream-base`). */
+  export type TokenConsumer<Item = unknown> = Flushable<Token, Item | Many<Item> | typeof none>;
+  /** Stage shape of the stringers: `tokens` → `text`. */
+  export type TokenStringer = Flushable<Token, string | typeof none>;
+
   /** Self-reference for backwards compat: `import {parser} from 'stream-json/core/parser.js'`. */
   export const parser: typeof import('./parser.js').default;
 }
 
 type Token = parser.Token;
 type TokenName = parser.TokenName;
 type ParserOptions = parser.ParserOptions;
+type TokenSource = parser.TokenSource;
+type TokenTransform = parser.TokenTransform;
+type TokenConsumer<Item = unknown> = parser.TokenConsumer<Item>;
+type TokenStringer = parser.TokenStringer;
 
 export default parser;
 export {parser};
-export type {Token, TokenName, ParserOptions};
+export type {Token, TokenName, ParserOptions, TokenSource, TokenTransform, TokenConsumer, TokenStringer};

src/core/streamers/stream-array.d.ts

@@ -1,6 +1,6 @@
 import {Flushable, Many, none} from 'stream-chain/defs.js';
 import parser from '../parser.js';
-import type {StreamBaseOptions} from './stream-base.js';
+import type {KeyedValue, StreamBaseOptions} from './stream-base.js';
 
 /**
  * Streams elements of a top-level JSON array as `{key, value}` objects.
@@ -12,24 +12,18 @@ import type {StreamBaseOptions} from './stream-base.js';
  *
  * @param options - Streamer options (assembler settings, `objectFilter`).
  */
-declare function streamArray<T = unknown>(
-  options?: StreamBaseOptions
-): Flushable<parser.Token, streamArray.StreamArrayItem<T> | typeof none | Many<streamArray.StreamArrayItem<T>>>;
+declare function streamArray<T = unknown>(options?: StreamBaseOptions): parser.TokenConsumer<streamArray.StreamArrayItem<T>>;
 
 declare namespace streamArray {
   /**
-   * An item emitted by `streamArray`: the array index and its assembled value.
+   * An item emitted by `streamArray` — `KeyedValue<number, T>`: `key` is the
+   * zero-based array index, `value` the assembled element.
    *
    * Generic in `T` (default `unknown`). Declare `StreamArrayItem<MyRow>` to type
    * the `value` field; the streamer factory and `.withParser` carry the parameter
    * through.
    */
-  export interface StreamArrayItem<T = unknown> {
-    /** Zero-based array index. */
-    key: number;
-    /** The fully assembled JavaScript value, typed as `T` (default `unknown`). */
-    value: T;
-  }
+  export type StreamArrayItem<T = unknown> = KeyedValue<number, T>;
   /** Creates a `parser() + streamArray()` pipeline as a flushable function. */
   export function withParser<T = unknown>(
     options?: StreamBaseOptions & parser.ParserOptions

src/core/streamers/stream-base.d.ts

@@ -36,11 +36,26 @@ declare namespace streamBase {
     /** Include objects for which `objectFilter` never made a decision. Default: `false`. */
     includeUndecided?: boolean;
   }
+
+  /**
+   * The common shape of every streamer's output item: a `{key, value}` pair.
+   *
+   * `K` is the key type: `string` for `streamObject` (the property name),
+   * `number` for `streamArray` (the array index) and `streamValues` (a
+   * sequential counter). `T` types the assembled `value`.
+   */
+  export interface KeyedValue<K extends string | number = string | number, T = unknown> {
+    /** The item's key: a property name, an array index, or a sequential counter. */
+    key: K;
+    /** The fully assembled JavaScript value, typed as `T` (default `unknown`). */
+    value: T;
+  }
 }
 
 type StreamBaseConfig = streamBase.StreamBaseConfig;
 type StreamBaseOptions = streamBase.StreamBaseOptions;
+type KeyedValue<K extends string | number = string | number, T = unknown> = streamBase.KeyedValue<K, T>;
 
 export default streamBase;
 export {streamBase};
-export type {StreamBaseConfig, StreamBaseOptions};
+export type {StreamBaseConfig, StreamBaseOptions, KeyedValue};

src/core/streamers/stream-object.d.ts

@@ -1,6 +1,6 @@
 import {Flushable, Many, none} from 'stream-chain/defs.js';
 import parser from '../parser.js';
-import type {StreamBaseOptions} from './stream-base.js';
+import type {KeyedValue, StreamBaseOptions} from './stream-base.js';
 
 /**
  * Streams top-level properties of a JSON object as `{key, value}` objects.
@@ -12,24 +12,18 @@ import type {StreamBaseOptions} from './stream-base.js';
  *
  * @param options - Streamer options (assembler settings, `objectFilter`).
  */
-declare function streamObject<T = unknown>(
-  options?: StreamBaseOptions
-): Flushable<parser.Token, streamObject.StreamObjectItem<T> | typeof none | Many<streamObject.StreamObjectItem<T>>>;
+declare function streamObject<T = unknown>(options?: StreamBaseOptions): parser.TokenConsumer<streamObject.StreamObjectItem<T>>;
 
 declare namespace streamObject {
   /**
-   * An item emitted by `streamObject`: the property key and its assembled value.
+   * An item emitted by `streamObject` — `KeyedValue<string, T>`: `key` is the
+   * property name, `value` the assembled property value.
    *
    * Generic in `T` (default `unknown`). Declare `StreamObjectItem<MyValue>` to
    * type the `value` field; the streamer factory and `.withParser` carry the
    * parameter through.
    */
-  export interface StreamObjectItem<T = unknown> {
-    /** Object property name. */
-    key: string;
-    /** The fully assembled JavaScript value, typed as `T` (default `unknown`). */
-    value: T;
-  }
+  export type StreamObjectItem<T = unknown> = KeyedValue<string, T>;
   /** Creates a `parser() + streamObject()` pipeline as a flushable function. */
   export function withParser<T = unknown>(
     options?: StreamBaseOptions & parser.ParserOptions