feat: add async extraction API (extractAsync, renderAsync, renderMapAsync)

Cooperative async scan loop that yields to the event loop via
scheduler.yield() (with setTimeout fallback), preventing main-thread
blocking on large inputs. Supports AbortSignal cancellation.

- src/async.ts: asyncScan with configurable yieldEvery (default 512)
- mod.ts: extractAsync, renderAsync, renderMapAsync on Duckling()
- All async methods tagged @experimental
- 17 new tests (correctness, cancellation, interleaving, render parity)
- Async benchmarks added to bench/extract.bench.ts
- README updated with async API docs and AsyncScanOptions reference

Bumps version to 0.3.0.

Author: ClaudiuCeia

README.md

@@ -63,6 +63,7 @@ TypeScript and running anywhere — Deno, Node, or the browser.
   - [Redact PII](#redact-pii)
   - [Render entities](#render-entities)
   - [Map entities to components](#map-entities-to-components)
+  - [Async extraction](#async-extraction)
   - [Custom entities](#custom-entities)
 - [Supported entities](#supported-entities)
 - [API reference](#api-reference)
@@ -71,6 +72,10 @@ TypeScript and running anywhere — Deno, Node, or the browser.
   - [`.render(text, fn)`](#rendertext-fn)
   - [`.renderMap(text, fn)`](#rendermaptext-fn)
   - [`.redact(text, opts?)`](#redacttext-opts)
+  - [`.extractAsync(text, opts?)`](#extractasynctext-opts)
+  - [`.renderAsync(text, fn, opts?)`](#renderasynctext-fn-opts)
+  - [`.renderMapAsync(text, fn, opts?)`](#rendermapasynctext-fn-opts)
+  - [`AsyncScanOptions`](#asyncscanoptions)
   - [`PIIParsers`](#piiparsers)
   - [`RedactOptions`](#redactoptions)
   - [`RenderFn`](#renderfn)
@@ -279,6 +284,43 @@ Like `.render()`, nested entities are handled automatically — child spans are
 mapped first, and the parent callback receives the already-mapped children as
 `(string | R)[]`.
 
+### Async extraction
+
+> **Experimental** — these methods are stable enough to use but the API may
+> change in a future minor release.
+
+Every method has an async counterpart (`extractAsync`, `renderAsync`,
+`renderMapAsync`) that periodically yields to the browser event loop during
+scanning. This prevents long inputs from blocking the main thread — no Web
+Worker needed:
+
+```ts
+import { Duckling } from "@claudiu-ceia/ts-duckling";
+
+const controller = new AbortController();
+
+const entities = await Duckling().extractAsync(longText, {
+  signal: controller.signal, // cancel early if needed
+  yieldEvery: 256, // yield every N scan positions (default 512)
+});
+```
+
+Uses
+[`scheduler.yield()`](https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/yield)
+when available (Chrome 129+, Edge 129+, Firefox 142+), falling back to
+`setTimeout(0)`.
+
+`renderMapAsync` is especially useful in UI frameworks — extract and map
+entities to React elements without blocking paint:
+
+```tsx
+const segments = await Duckling().renderMapAsync<JSX.Element>(
+  text,
+  ({ entity, children }) => <mark data-kind={entity.kind}>{children}</mark>,
+);
+// → ["plain text", <mark>...</mark>, " more text"]
+```
+
 ### Custom entities
 
 Define a parser that returns an `Entity`, then pass it to `Duckling`:
@@ -343,11 +385,22 @@ const entities = Duckling([Email.parser, Hashtag.parser]).extract(
 ### `Duckling()`
 
 ```ts
-function Duckling(): { extract; render; renderMap; redact };
+function Duckling(): {
+  extract;
+  extractAsync;
+  render;
+  renderAsync;
+  renderMap;
+  renderMapAsync;
+  redact;
+};
 function Duckling<T>(parsers: ParserTuple<T>): {
   extract;
+  extractAsync;
   render;
+  renderAsync;
   renderMap;
+  renderMapAsync;
   redact;
 };
 ```
@@ -400,6 +453,49 @@ Built on top of `.render()`. Extracts entities then replaces each matched span
 with `opts.mask` (default `"█"`). When `opts.kinds` is set, only those entity
 kinds are masked. Overlapping/nested spans are resolved via the span tree.
 
+### `.extractAsync(text, opts?)`
+
+> **Experimental** — this method is stable enough to use but may change in a
+> future minor release.
+
+```ts
+extractAsync(text: string, opts?: AsyncScanOptions): Promise<Entity[]>
+```
+
+Async version of `.extract()` that yields to the event loop periodically.
+Supports cancellation via `AbortSignal`.
+
+### `.renderAsync(text, fn, opts?)`
+
+> **Experimental** — this method is stable enough to use but may change in a
+> future minor release.
+
+```ts
+renderAsync(text: string, fn: RenderFn<Entity>, opts?: AsyncScanOptions): Promise<string>
+```
+
+Async version of `.render()`.
+
+### `.renderMapAsync(text, fn, opts?)`
+
+> **Experimental** — this method is stable enough to use but may change in a
+> future minor release.
+
+```ts
+renderMapAsync<R>(text: string, fn: RenderMapFn<Entity, R>, opts?: AsyncScanOptions): Promise<(string | R)[]>
+```
+
+Async version of `.renderMap()`.
+
+### `AsyncScanOptions`
+
+```ts
+interface AsyncScanOptions {
+  signal?: AbortSignal; // cancel the scan
+  yieldEvery?: number; // default: 512
+}
+```
+
 ### `PIIParsers`
 
 ```ts

bench/extract.bench.ts

@@ -50,3 +50,45 @@ Deno.bench("extract: default Duckling (mixed)", () => {
     throw new Error("expected at least one time entity");
   }
 });
+
+// ---------------------------------------------------------------------------
+// Async benchmarks
+// ---------------------------------------------------------------------------
+
+// Compare sync vs async overhead on PII-heavy text
+Deno.bench("extractAsync: PII-heavy (yieldEvery=512)", async () => {
+  const entities = await piiDuckling.extractAsync(textPII, { yieldEvery: 512 });
+  if (entities.length < 6) throw new Error("unexpected low match count");
+});
+
+Deno.bench("extractAsync: PII-heavy (yieldEvery=64)", async () => {
+  const entities = await piiDuckling.extractAsync(textPII, { yieldEvery: 64 });
+  if (entities.length < 6) throw new Error("unexpected low match count");
+});
+
+Deno.bench("extractAsync: PII-heavy (yieldEvery=8)", async () => {
+  const entities = await piiDuckling.extractAsync(textPII, { yieldEvery: 8 });
+  if (entities.length < 6) throw new Error("unexpected low match count");
+});
+
+// Large input: 5x repeated PII text (~1 KB)
+const textLarge = (textPII + " ").repeat(5);
+
+Deno.bench("extract: PII-heavy ×5 (sync)", () => {
+  const entities = piiDuckling.extract(textLarge);
+  if (entities.length < 30) throw new Error("unexpected low match count");
+});
+
+Deno.bench("extractAsync: PII-heavy ×5 (yieldEvery=512)", async () => {
+  const entities = await piiDuckling.extractAsync(textLarge, {
+    yieldEvery: 512,
+  });
+  if (entities.length < 30) throw new Error("unexpected low match count");
+});
+
+Deno.bench("extractAsync: PII-heavy ×5 (yieldEvery=64)", async () => {
+  const entities = await piiDuckling.extractAsync(textLarge, {
+    yieldEvery: 64,
+  });
+  if (entities.length < 30) throw new Error("unexpected low match count");
+});

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudiu-ceia/ts-duckling",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "exports": {
     ".": "./mod.ts"
   },

mod.ts

@@ -14,6 +14,7 @@ import {
   step,
 } from "@claudiu-ceia/combine";
 import { __, dot, word } from "./src/common.ts";
+import { asyncScan, type AsyncScanOptions } from "./src/async.ts";
 import { buildSpanTree, renderMapNode, renderNode } from "./src/render.ts";
 import type { RenderFn, RenderMapFn } from "./src/render.ts";
 import { Quantity, type QuantityEntity } from "./src/Quantity.ts";
@@ -141,6 +142,7 @@ export interface RedactOptions<K extends string = string> {
   kinds?: K[];
 }
 
+export type { AsyncScanOptions } from "./src/async.ts";
 export type {
   RenderEntity,
   RenderFn,
@@ -163,9 +165,26 @@ export type {
  */
 export function Duckling(): {
   extract: (text: string) => AnyEntity[];
+  /** @experimental */
+  extractAsync: (
+    text: string,
+    opts?: AsyncScanOptions,
+  ) => Promise<AnyEntity[]>;
   redact: (text: string, opts?: RedactOptions<AnyEntity["kind"]>) => string;
   render: (text: string, fn: RenderFn<AnyEntity>) => string;
+  /** @experimental */
+  renderAsync: (
+    text: string,
+    fn: RenderFn<AnyEntity>,
+    opts?: AsyncScanOptions,
+  ) => Promise<string>;
   renderMap: <R>(text: string, fn: RenderMapFn<AnyEntity, R>) => (string | R)[];
+  /** @experimental */
+  renderMapAsync: <R>(
+    text: string,
+    fn: RenderMapFn<AnyEntity, R>,
+    opts?: AsyncScanOptions,
+  ) => Promise<(string | R)[]>;
 };
 /**
  * Create an extractor with a specific set of parsers. The return type is
@@ -186,17 +205,34 @@ export function Duckling<T extends NonEmptyArray<unknown>>(
   parsers: ParserTuple<T>,
 ): {
   extract: (text: string) => T[number][];
+  /** @experimental */
+  extractAsync: (
+    text: string,
+    opts?: AsyncScanOptions,
+  ) => Promise<T[number][]>;
   redact: (
     text: string,
     opts?: RedactOptions<
       T[number] extends { kind: infer K extends string } ? K : string
     >,
   ) => string;
   render: (text: string, fn: RenderFn<T[number]>) => string;
+  /** @experimental */
+  renderAsync: (
+    text: string,
+    fn: RenderFn<T[number]>,
+    opts?: AsyncScanOptions,
+  ) => Promise<string>;
   renderMap: <R>(
     text: string,
     fn: RenderMapFn<T[number], R>,
   ) => (string | R)[];
+  /** @experimental */
+  renderMapAsync: <R>(
+    text: string,
+    fn: RenderMapFn<T[number], R>,
+    opts?: AsyncScanOptions,
+  ) => Promise<(string | R)[]>;
 };
 
 // deno-lint-ignore no-explicit-any
@@ -239,6 +275,34 @@ export function Duckling(parsers?: any): any {
 
   return {
     extract: parse,
+    /**
+     * @experimental
+     *
+     * Async version of {@link extract} that yields to the event loop
+     * periodically, preventing main-thread blocking on large inputs.
+     *
+     * Uses `scheduler.yield()` when available (Chrome 129+, Edge 129+,
+     * Firefox 142+), falling back to `setTimeout(0)`.
+     *
+     * @example
+     * ```ts
+     * const controller = new AbortController();
+     * const entities = await Duckling().extractAsync(longText, {
+     *   signal: controller.signal,
+     *   yieldEvery: 256,
+     * });
+     * ```
+     */
+    extractAsync: (
+      input: string,
+      opts?: AsyncScanOptions,
+    ): Promise<unknown[]> => {
+      return asyncScan(
+        input,
+        p as NonEmptyArray<Parser<unknown>>,
+        opts,
+      );
+    },
     /**
      * Replace entity spans using a callback function.
      *
@@ -275,6 +339,31 @@ export function Duckling(parsers?: any): any {
       const tree = buildSpanTree(all, input.length);
       return renderNode(tree, input, fn);
     },
+    /**
+     * @experimental
+     *
+     * Async version of {@link render} that yields to the event loop
+     * during entity extraction.
+     */
+    renderAsync: async (
+      input: string,
+      fn: RenderFn<unknown>,
+      opts?: AsyncScanOptions,
+    ): Promise<string> => {
+      const all = (await asyncScan(
+        input,
+        p as NonEmptyArray<Parser<unknown>>,
+        opts,
+      )) as {
+        kind: string;
+        start: number;
+        end: number;
+        text: string;
+      }[];
+      if (all.length === 0) return input;
+      const tree = buildSpanTree(all, input.length);
+      return renderNode(tree, input, fn);
+    },
     /**
      * Map entity spans to arbitrary values, returning an array of segments.
      *
@@ -309,6 +398,32 @@ export function Duckling(parsers?: any): any {
       const tree = buildSpanTree(all, input.length);
       return renderMapNode<R>(tree, input, fn);
     },
+    /**
+     * @experimental
+     *
+     * Async version of {@link renderMap} that yields to the event loop
+     * during entity extraction.
+     */
+    renderMapAsync: async <R>(
+      input: string,
+      // deno-lint-ignore no-explicit-any
+      fn: RenderMapFn<any, R>,
+      opts?: AsyncScanOptions,
+    ): Promise<(string | R)[]> => {
+      const all = (await asyncScan(
+        input,
+        p as NonEmptyArray<Parser<unknown>>,
+        opts,
+      )) as {
+        kind: string;
+        start: number;
+        end: number;
+        text: string;
+      }[];
+      if (all.length === 0) return [input];
+      const tree = buildSpanTree(all, input.length);
+      return renderMapNode<R>(tree, input, fn);
+    },
     /**
      * Extract entities and replace each matched span with a mask character.
      *