unitsdb 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,40 +1,99 @@
1
1
  # unitsdb
2
2
 
3
3
  UnitsDB in TypeScript: typed access to the units database — units,
4
- prefixes, dimensions, quantities — rebuilt from
4
+ prefixes, dimensions, quantities, currencies — generated from
5
5
  [unitsml/unitsdb](https://github.com/unitsml/unitsdb) releases.
6
6
 
7
7
  The native replacement for the retired Opal-compiled `@unitsml/unitsdb`;
8
8
  [the `unitsml-ts` stack](https://github.com/unitsml/unitsml-ts) consumes
9
9
  this package for all unitsdb resolution.
10
10
 
11
+ ## Installation
12
+
13
+ ```sh
14
+ npm install unitsdb
15
+ ```
16
+
17
+ This is an ES module package. Importing `Unitsdb` loads the bundled dataset
18
+ and builds its lookup indexes immediately; no separate data download or
19
+ initialization call is needed.
20
+
11
21
  ## Dataset provenance
12
22
 
13
23
  `src/data/unitsdb.json` is generated from the unitsdb YAML releases by
14
- `scripts/build-dataset.rb` (run it from a unitsdb-ruby checkout;
15
- `npm run dataset` copies the result into place). The dataset version
16
- tracks the unitsdb data tags — current: unitsdb v2.0.2.
24
+ `scripts/build-dataset.rb` (run it with unitsdb-ruby loadable;
25
+ `ruby scripts/build-dataset.rb DATA_DIR OUT` takes a unitsdb checkout,
26
+ `npm run dataset` copies the default output into place). The current
27
+ dataset is pinned to unitsdb commit `b210137` (unitsml/unitsdb#143; schema 2.2.0).
28
+
29
+ The generator refuses rather than guessing: every field the release
30
+ schema marks required must be present, loader errors abort the build, and
31
+ the YAML files must agree on one schema version. The dataset records its
32
+ own `provenance` — data repository/commit/tag/schema version, per-file
33
+ sha256 digests, generator digest and loader versions — exposed as
34
+ `Unitsdb.provenance`. The tests fail if the generator changes without the
35
+ dataset being regenerated.
36
+
37
+ Units carry the schema 2.2.0 fields `canonical_conversion` (exact
38
+ factor/offset strings and root units), `root_units`, `scale_reference`
39
+ and external `references`; the `scales` registry is bundled too.
17
40
 
18
41
  ## API
19
42
 
20
43
  ```ts
21
44
  import { Unitsdb } from "unitsdb";
22
45
 
23
- Unitsdb.findUnitBySymbolId("m"); // NISTu1 "meter"
46
+ Unitsdb.findUnitBySymbolId("m"); // NISTu1 "metre"
24
47
  Unitsdb.findUnitById("NISTu155"); // decibel
25
48
  Unitsdb.findPrefixBySymbolName("k"); // kilo (base 10, power 3)
26
49
  Unitsdb.findDimensionById("NISTd2"); // mass
27
- Unitsdb.findDimensionByVector("1"); // vector-string lookup
50
+ Unitsdb.findDimensionByVector("::::::1:"); // mass exponent vector
28
51
  Unitsdb.findQuantityById("q:frequency"); // resolves q: and NIST ids
52
+ Unitsdb.findCurrencyByCode("EUR"); // Euro
53
+ Unitsdb.findCurrencyByNumeric(978); // Euro
29
54
  ```
30
55
 
31
56
  Finders mirror the unitsml-ruby wrappers: units resolve through symbol
32
57
  ids, identifiers are first-wins, dimension components keep the record's
33
58
  own key order, and dimension vectors use the DIMS_VECTOR exponent order.
34
59
 
60
+ ## Migrating from `@unitsml/unitsdb`
61
+
62
+ Replace the retired `@unitsml/unitsdb` dependency and import with `unitsdb`.
63
+ Use the exported `Unitsdb` object directly, without a `bundled()` call.
64
+ Use the current camelCase methods for lookups and search:
65
+
66
+ ```ts
67
+ import { Unitsdb } from "unitsdb";
68
+
69
+ const euro = Unitsdb.findById("cur:EUR");
70
+ const matches = Unitsdb.search({ text: "Euro" });
71
+ const currencies = Unitsdb.search({ text: "Euro", type: "currencies" });
72
+ const euroSymbols = Unitsdb.findCurrenciesBySymbol("€");
73
+ const metre = Unitsdb.findUnitBySymbolId("m");
74
+ ```
75
+
76
+ Single-record finders return `undefined` when no record matches. Search and
77
+ currency symbol lookups return arrays. Search matches identifiers and names
78
+ case-insensitively; currency symbols accept Unicode signs or ASCII codes
79
+ such as `EUR`. The currently bundled dataset contains 178 currency records,
80
+ available through `Unitsdb.currencies`.
81
+
82
+ ## Dataset generation
83
+
84
+ `src/data/unitsdb.json` is generated from a unitsdb checkout's `data`
85
+ directory by `scripts/build-dataset.rb`, using the Ruby `unitsdb` library.
86
+ The script writes `/tmp/unitsdb-ts.json`; copy that file into
87
+ `src/data/unitsdb.json` to update the bundled dataset.
88
+
35
89
  ## Development
36
90
 
37
91
  ```sh
38
92
  npm install
39
93
  npm run build && npm test
94
+ npm run test:package
40
95
  ```
96
+
97
+ `test:package` builds and packs the package, installs the local tarball in
98
+ an isolated temporary consumer, and checks that its public API can read
99
+ the bundled data.