Documentation
From two lines to a reader that checks itself.
Start with the shortest thing that works. Reach for the next page only when something downstream starts acting on the rows.
npm install truecopyStart here
Quickstart
Two lines for rows and cells, and the one field that separates this from an extractor. Then the three steps that turn a reading into one that checks itself.
Tutorial - a reader that checks itself
Build a complete statement reader from an empty file. Six steps, each one runnable, each one adding a guarantee the step before did not have.
The command
npx truecopy a-document.pdf - the shortest way to find out whether this library is any use on your own files, before installing anything.
Why refusing matters
Two readers written for different documents, sharing no line of code, arrived at the same five rules. When two teams converge without speaking, that is not a preference - it is the shape of the problem.
Reading a document
readTable - the two-line path
truecopy/table
Rows and cells out of a file with no configuration at all, plus the field that says what the reading could not vouch for.
open - the door
truecopy/open
The only way from bytes to rows, with the caps, the deadline and the engine released. And a refusal your application can say in its own language.
layout - the cut, and where every value came from
truecopy/layout
Pure geometry over plain data. Three ways to find columns, and the coordinates that let a person point at a value instead of hunting for it.
notation - how a page writes a figure
truecopy/notation
That 1 234,50 and 1,234.50 are the same quantity says nothing about banks. It says how the page was typeset - and it is the part everybody rewrites and everybody gets wrong once.
Trusting a reading
signature - the schema learned from the rows
truecopy/signature
A table describes itself. The row that breaks what every other row does is a total, a balance, a footer - and recognising it needs no list of words.
contract - what an honest reading looks like
truecopy/contract
Three methods you must write, two with safe defaults, and the one rule the pipeline enforces - a reading that contradicts its document never comes back as sound.
kit - six rules, in your own test suite
truecopy/kit
An interface is dodged with a return null. An assertion is not. Drop the conformance kit into your gate with a corpus of your own documents.
schema - one declaration, two outputs
truecopy/schema
Write the schema once and get the check and the record type. Or bring the one you already wrote in Zod, Valibot or ArkType.
explain - see what the reading decided
truecopy/explain
The feature the popular extractors have and the careful ones forget. Text, not an image - it goes into a terminal, a CI log, a bug report and a test.
classify - is this the kind of document expected
truecopy/classify
A statement quoting the word invoice in a transaction label must not be filed as an invoice. Precedence, stated rather than smuggled into an ordering.
columns and roles - what a column holds, and what it is
truecopy/columns · truecopy/roles
Count what each column contains once, then deduce what it is from that. Recognising a header label only works on issuers you have already seen.
pattern - domain knowledge as data
truecopy/pattern
Everything that varies by market, by issuer or by document family should be a value, not a branch. And a pattern off the wire is untrusted input applied to untrusted input.