@carl.fyi/data

Turn messy input into dependable data: extract JSON, inspect Base64, reorder arrays and export clean CSV.

Interactive documentation

Install

npm install @carl.fyi/data

Quick start

import { extractJsonFromText, parseJsonFromText } from "@carl.fyi/data";

extractJsonFromText('Result: {"ok":true} done');
// => '{"ok":true}'

parseJsonFromText<{ ok: boolean }>('Result: {"ok":true}');
// => { ok: true }

Entry points

| Import | Purpose | | ------------------------- | ---------------------- | | @carl.fyi/data | All public exports | | @carl.fyi/data/arrays | Focused subpath import | | @carl.fyi/data/csv | Focused subpath import | | @carl.fyi/data/encoding | Focused subpath import | | @carl.fyi/data/json | Focused subpath import |

All entry points are ESM, side-effect-free, and include TypeScript declarations.

Public API

This is the complete export inventory. The detailed reference below mirrors the APIs demonstrated on the documentation website; its signatures, descriptions, defaults, errors, and examples are compiled from the package source.

| Export | Kind | Import from | Description | | --------------------- | --------- | ------------------------- | -------------------------------------------------------------------------- | | applySavedOrder | function | @carl.fyi/data/arrays | Reapply a stored identifier order and append previously unseen items. | | moveItem | function | @carl.fyi/data/arrays | Move one item to another index without mutating the source array. | | csvCell | function | @carl.fyi/data/csv | Encode one scalar value as a CSV cell. | | CsvOptions | interface | @carl.fyi/data/csv | Options controlling CSV columns and separators. | | CsvValue | type | @carl.fyi/data/csv | A scalar value that can be represented in a CSV cell. | | toCsv | function | @carl.fyi/data/csv | Encode records as delimiter-separated text with stable columns. | | base64ByteLength | function | @carl.fyi/data/encoding | Calculate the decoded byte length of a Base64 payload without decoding it. | | Base64Info | interface | @carl.fyi/data/encoding | Structural information derived from a Base64 payload. | | inspectBase64 | function | @carl.fyi/data/encoding | Inspect the shape and decoded byte length of Base64 or a Base64 data URL. | | extractJsonFromText | function | @carl.fyi/data/json | Return the first balanced top-level JSON object or array embedded in text. | | JsonContainer | type | @carl.fyi/data/json | A top-level JSON value supported by the extraction helpers. | | parseJsonFromText | function | @carl.fyi/data/json | Parse the first embedded JSON object or array. |

API reference

@carl.fyi/data/json

extractJsonFromText

extractJsonFromText(text: string): string | null

Return the first balanced top-level JSON object or array embedded in text.

Scans from left to right, tracks nested objects and arrays, and ignores structural characters inside quoted strings. A balanced candidate is returned verbatim and may still be invalid JSON; use parseJsonFromText when parsing is required.

| Parameter | Type | Description | | --------- | -------- | ----------------------------- | | text | string | The surrounding text to scan. |

Returns: The first balanced object or array substring, or null.

Example

import { extractJsonFromText } from "@carl.fyi/data";

extractJsonFromText('Result: {"ok":true} done');
// => '{"ok":true}'

parseJsonFromText

parseJsonFromText<T extends JsonContainer = JsonContainer>(text: string): T | null

Parse the first embedded JSON object or array.

Parses the first balanced candidate and makes one compatibility retry for literal line breaks inside strings. The generic type is a TypeScript assertion only; this function does not validate the parsed object against a schema.

| Parameter | Type | Description | | --------- | -------- | --------------------------------------------------- | | text | string | The surrounding text containing an object or array. |

Returns: The parsed object or array cast to T, or null on failure.

Example

import { parseJsonFromText } from "@carl.fyi/data";

parseJsonFromText<{ ok: boolean }>('Result: {"ok":true}');
// => { ok: true }

@carl.fyi/data/arrays

moveItem

moveItem<T>(items: readonly T[], fromIndex: number, toIndex: number): T[]

Move one item to another index without mutating the source array.

Both indices address the original array bounds. The selected item is removed and inserted at the destination in a shallow copy; item identities are retained.

| Parameter | Type | Description | | ----------- | -------------- | ----------------------------------------- | | items | readonly T[] | The source items to copy and reorder. | | fromIndex | number | The zero-based index of the item to move. | | toIndex | number | The zero-based destination index. |

Returns: A newly allocated array with the requested order.

Throws

• RangeError when either index is not an integer or is out of range.

Example

import { moveItem } from "@carl.fyi/data";

moveItem(["a", "b", "c"], 0, 2);
// => ["b", "c", "a"]

applySavedOrder

applySavedOrder<T>(items: readonly T[], savedIds: readonly string[], getId: (item: T) => string): T[]

Reapply a stored identifier order and append previously unseen items.

Unknown and repeated saved identifiers are ignored. Items absent from the saved order retain their current relative order. Identifiers should be unique; when they are not, the lookup keeps the last matching item and the result contains one item per identifier.

| Parameter | Type | Description | | ---------- | --------------------- | --------------------------------------------- | | items | readonly T[] | The current collection of items. | | savedIds | readonly string[] | Identifiers in the preferred persisted order. | | getId | (item: T) => string | Returns the stable identifier for an item. |

Returns: A new array containing known saved items first, then unsaved items.

Example

import { applySavedOrder } from "@carl.fyi/data";

applySavedOrder(["a", "b", "c"], ["c", "a"], (item) => item);
// => ["c", "a", "b"]

@carl.fyi/data/encoding

inspectBase64

inspectBase64(input: string): Base64Info

Inspect the shape and decoded byte length of Base64 or a Base64 data URL.

Trims surrounding whitespace, removes whitespace inside the payload, accepts standard and URL-safe alphabet characters, and calculates length without decoding. This is structural validation, not verification that the bytes represent the declared media type.

| Parameter | Type | Description | | --------- | -------- | ------------------------------------------------- | | input | string | A plain Base64 payload or a data:*;base64, URL. |

Returns: The normalized payload, media type, alphabet flag, and byte length.

Throws

• TypeError for a non-Base64 data URL or invalid payload shape.

Example

import { inspectBase64 } from "@carl.fyi/data";

inspectBase64("data:text/plain;base64,SGVsbG8=");
// => { data: "SGVsbG8=", mediaType: "text/plain", urlSafe: false, byteLength: 5 }

@carl.fyi/data/csv

toCsv

toCsv<Row extends Record<string, CsvValue>>(rows: readonly Row[], options?: CsvOptions<Row>): string

Encode records as delimiter-separated text with stable columns.

Columns default to the own enumerable keys of the first row. Missing and nullish cells become empty strings, dates use ISO format, and cells are escaped by csvCell. This function returns text only and does not write a file.

| Parameter | Type | Description | | ---------------------------------- | --------------------------------- | -------------------------------------------------------------- | | rows | readonly Row[] | The records to encode. | | options (optional) | CsvOptions<Row> | Optional columns, delimiter, header, and line-ending settings. | | options.columns (optional) | readonly (keyof Row & string)[] | Column keys in output order. Default: keys of the first row. | | options.delimiter (optional) | string | Single-character cell separator. Default: ",". | | options.includeHeader (optional) | boolean | Whether to include a header row. Default: true. | | options.newline (optional) | "\n" \| "\r\n" | Line ending inserted between records. Default: "\\n". |

Returns: The encoded text, or an empty string for empty inferred input.

Throws

• TypeError when the delimiter is not one safe character.

Example

import { toCsv } from "@carl.fyi/data";

toCsv([{ name: "Ada", note: "one,two" }]);
// => 'name,note\nAda,"one,two"'

License

MIT