@smartput/core

The engine: normalize, tokenize, parse, solve, eval, print.

Everything that turns text into a Result, and nothing that knows what a metre is. createEngine() composes locales and kinds into the six-stage pipeline; defineKind() and defineLocale() are how anything gets into it.

One runtime dependency, decimal.js, and that is a deliberate ceiling — check-deps.ts fails the build if a second one appears. Every stage is also its own subpath, so a consumer that wants only the tokenizer pays for only the tokenizer.

Setup

npm add @smartput/core

Example

import { composeLocale, createEngine } from "@smartput/core";
import { english } from "@smartput/core/locale/en";
import { BUILTIN_KINDS } from "@smartput/kinds";
import BUILTIN_EN from "@smartput/kinds/locale/en";

const engine = createEngine({
  locales: [composeLocale(english, BUILTIN_EN)],
  kinds: BUILTIN_KINDS,
});

engine.evaluate("1 kg + 500 g").formatted         // "1.5 kilograms"
engine.evaluate("2 km in m").formatted            // "2,000 metres"
engine.evaluate("20% of 250").formatted           // "50"
engine.evaluate("1 kg + 500 g").confidence        // 1
engine.complete("12 k").length                    // 10
engine.explain("10 m + 5 min").candidates.length  // 1

evaluate returns a Result — value, formatted, kind, confidence, spans, meta — and never throws on unreadable input. explain() returns the same run with every stage's intermediate state, which is what to reach for when a reading is not the one you expected.

Entry points

| Import | Contents | | --- | --- | | @smartput/core | The package root. | | @smartput/core/testing | assertKindContract — the contract every kind must satisfy. | | @smartput/core/normalize | Stage 1: case, spacing, digits, punctuation. | | @smartput/core/tokenize | Stage 2: text to Token[]. | | @smartput/core/parse | Stage 3: tokens to candidate readings. | | @smartput/core/solve | Stage 4: ranking, ambiguity, weights. | | @smartput/core/scan | See the source for what this subpath carries. | | @smartput/core/eval | Stage 5: the arithmetic, in Decimal. | | @smartput/core/print | Stage 6: formatValue and the locale number grammar. | | @smartput/core/registry | The kind/locale registry the stages read. | | @smartput/core/locale/<id> | One language's words for this kind. 17 ship: en, de, fr, es, pt, it, nl, zh, ja, ar, ru, pl, tr, hi, ko, id, uk. |

Runtime exports

Type-only exports are erased and do not appear here.

AmbiguityError · Autocompleter · BOOLEAN_KIND · BOOLEAN_UNIT · COMPARE_PRECISION · COMPARISON_OPS · CUE_CEILING · CountQueryError · DEFAULT_CUE_WINDOW · DEFAULT_DISPLAY · DEFAULT_MAX_SPAN · DISPLAY_PRECISION · Decimal · DimensionMismatchError · DivideByZeroError · EDIT_HEADROOM · EXACT_BONUS · Evaluator · KeywordConflictError · KindConflictError · LENGTH_PENALTY · LocaleMismatchError · MissingRateError · NUMBER_FALLBACK_WEIGHT · NUMBER_KIND · NoCandidateError · Normalizer · PERCENT_KIND · Parser · Printer · RateProviderError · RatesNotReadyError · SCALE_BONUS · Scanner · SmartputError · Solver · Tokenizer · TooAmbiguousError · UnitParseError · UnknownKindError · VocabularyConflictError · aliasesFor · applyDisplay · buildKeywords · buildProgram · buildRegistry · cardinalNumerals · cardinalSpeller · collectCues · complete · composeLocale · compoundSplitter · createAnalyzerChain · createCachedEngine · createEngine · createFacade · createFacades · createSnapshotCache · decimalRatios · defineKind · defineLanguage · defineVocabulary · deriveValue · editDistance · evaluateNode · foldLiterals · formatNumber · formatValue · generateComparisonOps · identity · nearestWord · normalize · phraseAnalyzer · prefixStripper · scriptSegmenter · solve · suffixStripper · tableAnalyzer · walk · wordsFor

Dependencies

• @smartput/kind
• decimal.js

Generated by scripts/gen-readmes.ts — run bun run docs:readmes. Every output above was produced by running the line beside it. The full page, with live demos, is docs/packages/core.md.