marc-ts 0.1.0 → 0.2.0

package/README.md

@@ -7,12 +7,11 @@
 
 ## Features
 
-- **Immutable API** - All operations return new objects, never mutate existing records
-- **Zero runtime dependencies** - Works in browsers and Node.js (≥14) without any dependencies
-- **Type-safe** - Full TypeScript type definitions with strict typing
-- **Well-tested** - >90% code coverage with comprehensive test suite
-- **Universal** - Runs in Node.js and modern browsers (Chrome, Firefox, Safari, Edge)
-- **Functional design** - Pure functions for composability and predictability
+- **Four formats** — ISO2709 binary, MARCXML, MARC-in-JSON, MARCBreaker/marctxt
+- **Consistent API** — every format uses `parse*(input) → MarcRecord[]` and `serialize*(records[]) → <native>`
+- **Immutable** — all operations return new objects, never mutate
+- **Zero dependencies** — works in Node.js and modern browsers
+- **Fully typed** — strict TypeScript throughout
 
 ## Installation
 
@@ -23,620 +22,318 @@ npm install marc-ts
 ## Quick Start
 
 ```typescript
-import { parseMarcRecord, serializeMarcRecord, title, author, isbn, subjects } from 'marc-ts';
+import { parseMarcBinary, serializeMarcBinary, title, author } from 'marc-ts';
 import { parseMarcXml, serializeMarcXml } from 'marc-ts/xml';
 import { parseMarcJson, serializeMarcJsonString } from 'marc-ts/json';
 import { parseMarcTxt, serializeMarcTxt } from 'marc-ts/txt';
 
-// --- ISO 2709 binary (MARC21) ---
-const buffer = new Uint8Array([...]); // Your MARC21 binary data
-const result = parseMarcRecord(buffer);
+// Binary (ISO2709) — splits on 0x1D, returns all records
+const records = parseMarcBinary(buffer);
+console.log(title(records[0]));
+console.log(author(records[0]));
+const binary = serializeMarcBinary(records);
 
-if (result.record) {
-  console.log('Title:', title(result.record));
-  console.log('Author:', author(result.record));
-  console.log('ISBNs:', isbn(result.record));
-  console.log('Subjects:', subjects(result.record));
-}
-if (result.warnings.length > 0) {
-  console.warn('Parsing warnings:', result.warnings);
-}
-
-// Serialize back to binary (UTF-8 by default; pass { encoding: 'marc8' } for MARC-8 output)
-const binary = serializeMarcRecord(result.record!, { encoding: 'utf8' });
-
-// --- MARCXML ---
-const xmlString = `<?xml version="1.0"?>
-<collection xmlns="http://www.loc.gov/MARC21/slim">
-  <record>
-    <leader>00000nam a2200000   4500</leader>
-    <datafield tag="245" ind1="1" ind2="0">
-      <subfield code="a">The Hobbit</subfield>
-    </datafield>
-  </record>
-</collection>`;
-
-const [xmlRecord] = parseMarcXml(xmlString);
-console.log('Title from XML:', title(xmlRecord));
-const roundtripXml = serializeMarcXml([xmlRecord]); // back to a <collection> document
-
-// --- MARC-in-JSON ---
-const jsonString = JSON.stringify({
-  leader: '00000nam a2200000   4500',
-  fields: [
-    { '245': { subfields: [{ a: 'The Hobbit' }], ind1: '1', ind2: '0' } },
-  ],
-});
-
-const jsonRecord = parseMarcJson(jsonString);
-console.log('Title from JSON:', title(jsonRecord));
-const roundtripJson = serializeMarcJsonString(jsonRecord); // back to a JSON string
-
-// --- MARCBreaker (marctxt) ---
-const txtString = `=LDR  00000nam a2200000   4500
-=001  5490
-=245  10$aThe Hobbit /$cJ.R.R. Tolkien.
-`;
-
-const [txtRecord] = parseMarcTxt(txtString);
-console.log('Title from marctxt:', title(txtRecord));
-const roundtripTxt = serializeMarcTxt([txtRecord]); // back to marctxt string
-
-// --- MARC-8 binary ---
-// parseMarcRecord detects MARC-8 automatically from leader byte 9 (' ');
-// records are decoded to Unicode transparently — no special handling needed.
-const marc8Buffer = new Uint8Array([...]); // MARC-8 encoded binary
-const marc8Result = parseMarcRecord(marc8Buffer); // decoded to Unicode automatically
-```
-
-## Why marc-ts?
+// MARCXML — parses <collection> or bare <record> elements
+const xmlRecords = parseMarcXml(xmlString);
+const xml = serializeMarcXml(xmlRecords);
 
-Existing JavaScript/TypeScript MARC libraries are often:
-- Node.js-only (using streams, fs, Buffer APIs)
-- Class-based OOP patterns that don't leverage TypeScript's strengths
-- Mutable APIs that can lead to unexpected bugs
-- Lacking comprehensive type definitions
+// MARC-in-JSON — accepts array, single object, or JSON string
+const jsonRecords = parseMarcJson(jsonString);
+const json = serializeMarcJsonString(jsonRecords);
 
-**marc-ts** addresses these limitations:
-- Universal browser and Node.js compatibility
-- TypeScript-native with full type safety and functional patterns
-- Immutable operations for safer, more predictable code
-- Zero runtime dependencies for minimal bundle size
-
-## Core Concepts
-
-### Immutability
-
-Mutation-style operations in **marc-ts** return new records or fields rather than modifying existing ones:
-
-```typescript
-const updated = appendField(record, field); // record remains unchanged
+// MARCBreaker — records separated by blank lines
+const txtRecords = parseMarcTxt(txtString);
+const txt = serializeMarcTxt(txtRecords);
 ```
 
-This approach prevents accidental mutations and makes code easier to reason about, especially in reactive frameworks like React or Vue.
+## Formats
 
-### Functional API
-
-**marc-ts** uses pure functions for maximum composability:
+### ISO2709 Binary (`marc-ts`)
 
 ```typescript
-// Extract metadata using pure functions
-const bookTitle = title(record);
-const bookAuthor = author(record);
-
-// Access fields functionally
-const titleField = getField(record, '245');
+import { parseMarcBinary, serializeMarcBinary } from 'marc-ts';
+import type { ParseOptions, SerializeOptions } from 'marc-ts';
 ```
 
-### Type Safety
+#### `parseMarcBinary(buffer, options?): MarcRecord[]`
 
-Full TypeScript types ensure compile-time correctness:
+Parse a concatenated ISO2709 binary stream. Splits on `0x1D` (RECORD_TERMINATOR) and parses each record. Records that fail to parse are silently skipped in lenient mode; with `strict: true` the first error throws.
 
 ```typescript
-import type { MarcRecord, DataField } from 'marc-ts';
-import { isDataField } from 'marc-ts';
-
-const field = getField(record, '245');
-if (field && isDataField(field)) {
-  // TypeScript knows field is a DataField
-  const titleValue = getSubfield(field, 'a');
-}
+const records = parseMarcBinary(buffer);
+const strict = parseMarcBinary(buffer, { strict: true });
 ```
 
-## API Reference
-
-### Parsing and Serialization
+**`ParseOptions`**
 
-#### `parseMarcRecord(buffer, options?): ParseResult`
-
-Parse ISO2709 binary data into a MARC record.
-
-```typescript
-const result = parseMarcRecord(buffer, {
-  strict: false, // If true, throw on fatal parse errors
-  maxWarnings: 100, // Maximum warnings to collect
-});
-
-if (result.record) {
-  // Successfully parsed
-} else {
-  // Parsing failed, check result.warnings
-}
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `strict` | `boolean` | `false` | Throw on fatal parse errors instead of skipping |
+| `maxWarnings` | `number` | `100` | Stop collecting warnings after this many |
 
-Recoverable issues may still be returned in `warnings`, such as MARC leader compatibility warnings.
+**Character encoding.** Leader byte 9 controls decoding: `'a'` = UTF-8, `' '` (space) = MARC-8. MARC-8 decoding handles ANSEL Latin, Greek, Hebrew, Cyrillic, Arabic, and subscript/superscript scripts via escape-designated sequences. EACC/CJK coverage is limited (~33 of ~16,000 official triples); records with substantial CJK content will mostly decode to U+FFFD — prefer UTF-8 sources for CJK catalogs.
 
-#### `parseMarcRecordStrict(buffer): MarcRecord`
+#### `serializeMarcBinary(records, options?): Uint8Array`
 
-Convenience wrapper for strict parsing (throws on fatal parse errors).
+Serialize an array of records to a concatenated ISO2709 binary stream. Each record is individually serialized with its own `0x1D` terminator.
 
 ```typescript
-try {
-  const record = parseMarcRecordStrict(buffer);
-} catch (error) {
-  console.error('Parsing failed:', error);
-}
+const buffer = serializeMarcBinary(records);
+const marc8Buffer = serializeMarcBinary(records, { encoding: 'marc8' });
 ```
 
-#### `serializeMarcRecord(record): Uint8Array`
+**`SerializeOptions`**
 
-Serialize a MARC record to ISO2709 binary format.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `encoding` | `'utf8' \| 'marc8'` | `'utf8'` | Character encoding; `'marc8'` replaces unsupported Unicode with `?` |
 
-```typescript
-const buffer = serializeMarcRecord(record);
-// Can be written to file or transmitted over network
-```
+---
 
-`parseMarcRecord` decodes UTF-8 records and MARC-8 records signaled by leader
-byte 9. MARC-8 decoding handles escape-designated scripts such as ANSEL Latin,
-Greek, Hebrew, Cyrillic, Arabic, subscript/superscript, and mapped EACC/CJK
-triples. MARC-8 serialization is intentionally conservative: `encoding:
-'marc8'` writes ASCII plus ANSEL Latin/combining characters and replaces
-unsupported Unicode characters with `?`.
-
-**EACC coverage caveat:** the bundled EACC table maps only ~33 of the ~16,000
-official triples. Records with substantial Chinese/Japanese/Korean content
-will mostly decode to U+FFFD. For CJK catalogs, prefer UTF-8 sources
-(`leader[9] === 'a'`).
-
-**Surfacing lossy MARC-8 encoding:** because `serializeMarcRecord` returns a
-plain `Uint8Array`, lossy substitutions are invisible to callers. Use
-`serializeMarcRecordWithWarnings(record, { encoding: 'marc8' })` to get
-`{ bytes, warnings }` — any character that could not be encoded surfaces as
-an `encoding_error` warning. For just-the-encoder visibility, use
-`unicodeToMarc8WithStats(text)` to get `{ bytes, lossyCount }`.
-
-### Convenience Accessors
-
-Extract common bibliographic metadata:
-
-| Function | Field | Description | Example |
-|----------|-------|-------------|---------|
-| `title(record)` | 245 $a$b | Full title with subtitle | `"The Catcher in the Rye"` |
-| `titleProper(record)` | 245 $a | Main title only | `"The Catcher in the Rye"` |
-| `author(record)` | 100/110 $a | Main author/creator | `"Salinger, J. D."` |
-| `edition(record)` | 250 $a | Edition statement | `"1st ed."` |
-| `publisher(record)` | 260/264 $b | Publisher name | `"Little, Brown,"` |
-| `publicationDate(record)` | 260/264 $c | Publication date | `"1951."` |
-| `isbn(record)` | 020 $a | ISBN(s) - array | `["978-0-316-76948-0"]` |
-| `issn(record)` | 022 $a | ISSN | `"0028-0836"` |
-| `lccn(record)` | 010 $a | Library of Congress Control Number | `"50011915"` |
-| `subjects(record)` | 6XX $a | All subject headings - array | `["Fiction", "History"]` |
-| `seriesStatement(record)` | 490 $a | Series statement | `"Penguin classics"` |
-
-### Field Access
-
-#### `getField(record, tag): ControlField | DataField | undefined`
-
-Get the first field with a specific tag.
+### MARCXML (`marc-ts/xml`)
 
 ```typescript
-const titleField = getField(record, '245');
+import { parseMarcXml, serializeMarcXml } from 'marc-ts/xml';
 ```
 
-#### `getFields(record, tag): (ControlField | DataField)[]`
+#### `parseMarcXml(xml): MarcRecord[]`
 
-Get all fields with a specific tag.
+Parse a MARCXML string. Accepts a `<collection>` document, bare `<record>` elements, or namespace-prefixed variants (e.g. `marc:record`). Returns all records found; returns `[]` for empty or record-free input.
 
 ```typescript
-const subjectFields = getFields(record, '650');
+const records = parseMarcXml(xmlString);
 ```
 
-#### `getSubfield(field, code): string | undefined`
+#### `serializeMarcXml(records): string`
 
-Get the first subfield value from a data field.
+Serialize records to a full MARCXML `<collection>` document with XML declaration and MARC21 namespace.
 
 ```typescript
-const field = getField(record, '245');
-if (field && isDataField(field)) {
-  const titleValue = getSubfield(field, 'a');
-}
+const xml = serializeMarcXml(records);
 ```
 
-#### `getSubfields(field, code): string[]`
+---
 
-Get all subfield values with a specific code (for repeatable subfields).
+### MARC-in-JSON (`marc-ts/json`)
 
 ```typescript
-const field = getField(record, '650');
-if (field && isDataField(field)) {
-  const subdivisions = getSubfields(field, 'x');
-}
+import { parseMarcJson, serializeMarcJson, serializeMarcJsonString } from 'marc-ts/json';
+import type { MarcJsonObject } from 'marc-ts/json';
 ```
 
-#### `getAllSubfields(field): Array<{ code: string; value: string }>`
+The [MARC-in-JSON](https://wiki.code4lib.org/MARCJSONification) format represents each field as a single-key object:
 
-Get all subfields from a data field.
-
-```typescript
-const field = getField(record, '245');
-if (field && isDataField(field)) {
-  const allSubfields = getAllSubfields(field);
+```json
+{
+  "leader": "01142cam a2200301 a 4500",
+  "fields": [
+    { "001": "5490" },
+    { "245": { "subfields": [{ "a": "The Hobbit" }], "ind1": "1", "ind2": "0" } }
+  ]
 }
 ```
 
-### Wildcard Querying
-
-#### `getFieldsByPattern(record, pattern): (ControlField | DataField)[]`
-
-Match fields using wildcard patterns (`.` or `X` = any digit).
-
-```typescript
-// Get all 6XX subject fields
-const subjects = getFieldsByPattern(record, '6..');
-
-// Get all 7XX added entry fields
-const addedEntries = getFieldsByPattern(record, '7XX');
-
-// Get all X00 fields (100, 200, ..., 900)
-const x00Fields = getFieldsByPattern(record, 'X00');
-```
-
-#### `getFirstFieldByPattern(record, pattern): ControlField | DataField | undefined`
-
-Get the first field matching a wildcard pattern.
-
-```typescript
-const firstSubject = getFirstFieldByPattern(record, '6..');
-```
+#### `parseMarcJson(json): MarcRecord[]`
 
-### Field Operations (Immutable)
+Parse MARC-in-JSON into records. Accepts:
+- A JSON string whose top-level value is an array or a single object
+- A `MarcJsonObject[]` array
+- A single `MarcJsonObject`
 
-All operations return new records/fields without mutating the original.
-
-#### `appendField(record, field): MarcRecord`
-
-Append a field to the end of a record.
+Always returns `MarcRecord[]`. Throws on structural errors.
 
 ```typescript
-const newField: DataField = {
-  tag: '650',
-  indicator1: ' ',
-  indicator2: '0',
-  subfields: [{ code: 'a', value: 'New subject' }],
-};
-
-const updated = appendField(record, newField);
-// record is unchanged, updated has the new field
+const records = parseMarcJson(jsonString);       // JSON string (array or single)
+const records = parseMarcJson([obj1, obj2]);     // plain object array
+const records = parseMarcJson(singleObj);        // single object → one-element array
 ```
 
-#### `insertFieldBefore(record, tag, field): MarcRecord`
+#### `serializeMarcJson(records): MarcJsonObject[]`
 
-Insert a field before the first occurrence of a tag.
+Serialize records to an array of MARC-in-JSON plain objects.
 
 ```typescript
-const updated = insertFieldBefore(record, '700', newField);
+const objs = serializeMarcJson(records);
 ```
 
-#### `insertFieldAfter(record, tag, field): MarcRecord`
+#### `serializeMarcJsonString(records): string`
 
-Insert a field after the first occurrence of a tag.
+Serialize records directly to a JSON string (a JSON array).
 
 ```typescript
-const updated = insertFieldAfter(record, '245', newField);
+const json = serializeMarcJsonString(records);
 ```
 
-#### `insertGroupedField(record, field): MarcRecord`
-
-Insert a field maintaining MARC block order (00X → 0XX → 1XX → ... → 9XX).
-
-```typescript
-const updated = insertGroupedField(record, field);
-// Field is inserted in proper MARC order
-```
-
-#### `removeFields(record, tag): MarcRecord`
+---
 
-Remove all fields with a specific tag.
+### MARCBreaker / marctxt (`marc-ts/txt`)
 
 ```typescript
-const updated = removeFields(record, '650');
+import { parseMarcTxt, serializeMarcTxt } from 'marc-ts/txt';
 ```
 
-#### `removeField(record, field): MarcRecord`
-
-Remove a specific field instance using reference equality.
+MARCBreaker is a human-readable line-oriented format. Each field occupies one line; blank indicators are written as `\`; subfields use `$` followed by a single-character code. Records are separated by blank lines:
 
-```typescript
-const field = getField(record, '650');
-const updated = field ? removeField(record, field) : record;
 ```
-
-#### Subfield Operations
-
-```typescript
-// Add subfield to a field
-const updated = addSubfield(field, 'b', 'Subtitle');
-
-// Remove all subfields with code
-const updated = removeSubfield(field, 'x');
-
-// Replace first subfield with code
-const updated = replaceSubfield(field, 'a', 'New value');
+=LDR  00706cam a2200217 a 4500
+=001  5490
+=003  OCoLC
+=245  14$aThe Hobbit /$cJ.R.R. Tolkien.
+=650  \1$aHobbits (Fictitious characters)$vFiction.
 ```
 
-### Clone and Equality
-
-#### `cloneRecord(record): MarcRecord`
+**Value escaping** — reserved characters in field values are escaped as follows:
 
-Create a deep copy of a record.
+| Character | Escaped form |
+|-----------|-------------|
+| `$` | `{dollar}` |
+| `{` | `{lcub}` |
+| `}` | `{rcub}` |
+| `\` | `{bsol}` |
 
-```typescript
-const copy = cloneRecord(record);
-// Modifying copy will not affect record
-```
+Embedded newlines in values are replaced with a space on serialize.
 
-#### `recordsEqual(a, b, ignoreFieldOrder?): boolean`
+#### `parseMarcTxt(text): MarcRecord[]`
 
-Check if two records are equal.
+Parse a marctxt string. Accepts `\n` and `\r\n` line endings. Records are separated by blank lines. Returns all records found.
 
 ```typescript
-if (recordsEqual(record1, record2)) {
-  console.log('Records are identical');
-}
-
-// Ignore field order
-if (recordsEqual(record1, record2, true)) {
-  console.log('Records have same content');
-}
+const records = parseMarcTxt(txtString);
 ```
 
-#### `fieldsEqual(a, b): boolean`
+#### `serializeMarcTxt(records): string`
 
-Check if two fields are equal.
+Serialize records to a marctxt string, with records separated by blank lines.
 
 ```typescript
-if (fieldsEqual(field1, field2)) {
-  console.log('Fields are identical');
-}
+const txt = serializeMarcTxt(records);
 ```
 
-### Warnings
+---
 
-#### `createWarning(type, message, position?, tag?): MarcWarning`
+## Convenience Accessors
 
-Create a parsing warning object.
+Extract common bibliographic metadata from any `MarcRecord`:
 
 ```typescript
-const warning = createWarning('invalid_field', 'Field is out of bounds', 42, '245');
+import { title, titleProper, author, edition, publisher, publicationDate,
+         isbn, issn, lccn, subjects, seriesStatement } from 'marc-ts';
 ```
 
-## Additional Formats
-
-### MARCXML (`marc-ts/xml`)
-
-Import from the `marc-ts/xml` subpath for MARCXML support (Library of Congress schema).
+| Function | Source field | Returns |
+|----------|-------------|---------|
+| `title(record)` | 245 $a$b | Full title with subtitle |
+| `titleProper(record)` | 245 $a | Main title only |
+| `author(record)` | 100/110 $a | Main author/creator |
+| `edition(record)` | 250 $a | Edition statement |
+| `publisher(record)` | 260/264 $b | Publisher name |
+| `publicationDate(record)` | 260/264 $c | Publication date |
+| `isbn(record)` | 020 $a | `string[]` of ISBNs |
+| `issn(record)` | 022 $a | ISSN |
+| `lccn(record)` | 010 $a | Library of Congress Control Number |
+| `subjects(record)` | 6XX $a | `string[]` of subject headings |
+| `seriesStatement(record)` | 490 $a | Series statement |
 
-```typescript
-import {
-  parseMarcXml,
-  parseMarcXmlRecord,
-  serializeMarcXml,
-  serializeMarcXmlRecord,
-} from 'marc-ts/xml';
-```
-
-#### `parseMarcXml(xml): MarcRecord[]`
+---
 
-Parse a MARCXML string containing a `<collection>` or one or more bare `<record>` elements.
+## Field Access
 
 ```typescript
-const records = parseMarcXml(xmlString);
-// Returns all records found in the document
+import { getField, getFields, getSubfield, getSubfields, getAllSubfields } from 'marc-ts';
+import { isControlField, isDataField } from 'marc-ts';
 ```
 
-#### `parseMarcXmlRecord(xml): MarcRecord`
-
-Parse a MARCXML string expected to contain exactly one `<record>`. Throws if none is found.
+#### `getField(record, tag)` / `getFields(record, tag)`
 
 ```typescript
-const record = parseMarcXmlRecord(xmlString);
+const field = getField(record, '245');        // first match or undefined
+const fields = getFields(record, '650');      // all matches
 ```
 
-#### `serializeMarcXml(records): string`
-
-Serialize one or more records into a full MARCXML `<collection>` document (with XML declaration).
+#### `getSubfield(field, code)` / `getSubfields(field, code)`
 
 ```typescript
-const xml = serializeMarcXml([record1, record2]);
+if (field && isDataField(field)) {
+  const a = getSubfield(field, 'a');          // first $a or undefined
+  const xs = getSubfields(field, 'x');        // all $x values
+}
 ```
 
-#### `serializeMarcXmlRecord(record): string`
-
-Serialize a single record to a `<record>` XML element string (no collection wrapper or XML declaration).
+#### `getAllSubfields(field)`
 
 ```typescript
-const recordXml = serializeMarcXmlRecord(record);
+const all = getAllSubfields(field);           // [{ code, value }, ...]
 ```
 
 ---
 
-### MARC-in-JSON (`marc-ts/json`)
-
-Import from the `marc-ts/json` subpath for [MARC-in-JSON](https://wiki.code4lib.org/MARCJSONification) support (used by Open Library and many REST APIs).
+## Wildcard Querying
 
 ```typescript
-import {
-  parseMarcJson,
-  serializeMarcJson,
-  serializeMarcJsonString,
-} from 'marc-ts/json';
-import type { MarcJsonObject } from 'marc-ts/json';
-```
-
-The format represents each field as a single-key object in an array:
+import { getFieldsByPattern, getFirstFieldByPattern } from 'marc-ts';
 
-```json
-{
-  "leader": "01142cam a2200301 a 4500",
-  "fields": [
-    { "001": "5490" },
-    { "245": { "subfields": [{ "a": "The Hobbit" }], "ind1": "1", "ind2": "0" } }
-  ]
-}
-```
-
-#### `parseMarcJson(json): MarcRecord`
-
-Parse a MARC-in-JSON object or JSON string into a `MarcRecord`. Throws on structural errors.
-
-```typescript
-const record = parseMarcJson(jsonString);      // from a JSON string
-const record = parseMarcJson(jsonObject);      // from a plain object
+const subjects = getFieldsByPattern(record, '6..');   // all 6XX fields
+const first7xx = getFirstFieldByPattern(record, '7XX');
 ```
 
-#### `serializeMarcJson(record): MarcJsonObject`
-
-Serialize a `MarcRecord` to a MARC-in-JSON plain object.
-
-```typescript
-const obj = serializeMarcJson(record);
-// obj.leader, obj.fields — ready for JSON.stringify or further processing
-```
-
-#### `serializeMarcJsonString(record): string`
-
-Serialize a `MarcRecord` directly to a JSON string.
-
-```typescript
-const json = serializeMarcJsonString(record);
-```
+`.` and `X` each match any single digit.
 
 ---
 
-### MARCBreaker / marctxt (`marc-ts/txt`)
+## Field Operations (Immutable)
 
-Import from the `marc-ts/txt` subpath for MARCBreaker support. This format (also called MARCMaker or marctxt) is a human-readable line-oriented representation originated by the Library of Congress MARCMaker/MARCBreaker tools and widely used for editing MARC data in plain text.
+All operations return a new `MarcRecord` without modifying the original.
 
 ```typescript
 import {
-  parseMarcTxt,
-  parseMarcTxtRecord,
-  serializeMarcTxt,
-  serializeMarcTxtRecord,
-} from 'marc-ts/txt';
-```
-
-Each field occupies one line. Blank indicators are written as `\`. Subfields use `$` followed by a single-character code. Records are separated by blank lines:
-
-```
-=LDR  00706cam a2200217 a 4500
-=001  5490
-=003  OCoLC
-=245  14$aThe Hobbit /$cJ.R.R. Tolkien.
-=650  \1$aHobbits (Fictitious characters)$vFiction.
-```
-
-**Value escaping.** Standard MARCBreaker has no way to represent a literal `$`
-in a value, and `marc-ts` follows the same convention as other tools for the
-remaining reserved characters:
+  appendField, insertFieldBefore, insertFieldAfter, insertGroupedField,
+  removeFields, removeField,
+  addSubfield, removeSubfield, replaceSubfield,
+} from 'marc-ts';
 
-- `$` → `{dollar}`
-- `{` → `{lcub}`, `}` → `{rcub}`
-- `\` → `{bsol}`
+const r1 = appendField(record, newField);
+const r2 = insertFieldBefore(record, '700', newField);
+const r3 = insertFieldAfter(record, '245', newField);
+const r4 = insertGroupedField(record, newField);  // maintains MARC block order
+const r5 = removeFields(record, '650');
+const r6 = removeField(record, specificField);    // reference equality
 
-Embedded newlines (`\n`) in field values are replaced with a space on
-serialize, matching the behavior of other MARCBreaker tools. Source values that
-do not contain any of these characters are emitted verbatim.
-
-#### `parseMarcTxt(text): MarcRecord[]`
-
-Parse a marctxt string containing one or more records separated by blank lines. Accepts both `\n` and `\r\n` line endings.
-
-```typescript
-const records = parseMarcTxt(txtString);
-// Returns all records found
+// Subfield operations — return a new DataField
+const f1 = addSubfield(field, 'b', 'Subtitle');
+const f2 = removeSubfield(field, 'x');
+const f3 = replaceSubfield(field, 'a', 'New value');
 ```
 
-#### `parseMarcTxtRecord(text): MarcRecord`
+---
 
-Parse a marctxt string expected to contain exactly one record. Throws if none is found.
+## Clone and Equality
 
 ```typescript
-const record = parseMarcTxtRecord(txtString);
-```
-
-#### `serializeMarcTxt(records): string`
-
-Serialize one or more records into a marctxt string, with records separated by blank lines.
+import { cloneRecord, recordsEqual, fieldsEqual } from 'marc-ts';
 
-```typescript
-const txt = serializeMarcTxt([record1, record2]);
+const copy = cloneRecord(record);
+recordsEqual(a, b);              // strict field order
+recordsEqual(a, b, true);        // ignore field order
+fieldsEqual(field1, field2);
 ```
 
-#### `serializeMarcTxtRecord(record): string`
+---
 
-Serialize a single record to marctxt (no surrounding blank line).
+## Types
 
 ```typescript
-const txt = serializeMarcTxtRecord(record);
+import type { MarcRecord, ControlField, DataField, Subfield,
+              ParseOptions, SerializeOptions, MarcWarning, MarcWarningType } from 'marc-ts';
 ```
 
 ---
 
-## Browser Usage
-
-**marc-ts** works in modern browsers without any bundler configuration:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>marc-ts Browser Example</title>
-</head>
-<body>
-  <input type="file" id="fileInput" accept=".mrc" />
-  <pre id="output"></pre>
-
-  <script type="module">
-    import { parseMarcRecord, title, author } from 'https://cdn.skypack.dev/marc-ts';
-
-    document.getElementById('fileInput').addEventListener('change', async (e) => {
-      const file = e.target.files[0];
-      const arrayBuffer = await file.arrayBuffer();
-      const buffer = new Uint8Array(arrayBuffer);
-
-      const result = parseMarcRecord(buffer);
-      if (result.record) {
-        document.getElementById('output').textContent = `
-Title: ${title(result.record) || 'N/A'}
-Author: ${author(result.record) || 'N/A'}
-        `;
-      }
-    });
-  </script>
-</body>
-</html>
-```
-
-## Examples
-
-See the [examples/](./examples/) directory for more examples:
-- [basic-usage.ts](./examples/basic-usage.ts) - Common usage patterns
-- [browser.html](./examples/browser.html) - Browser integration
-
 ## Development
 
-Requires Node.js **20.19** or **22.12+** (driven by Vite 8). Older Node versions
-are EOL and will fail to install the dev toolchain. The compiled output is
-compatible with modern browsers and any actively-supported Node release.
+Requires Node.js **20.19** or **22.12+** (driven by Vite 8). The compiled output targets modern browsers and any actively-supported Node release.
+
+```bash
+npm test            # run tests
+npm run build       # compile to dist/
+npm run type-check  # TypeScript check without emit
+```