unitsdb 0.1.2 → 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 +65 -6
- package/dist/data/unitsdb.json +1 -1
- package/dist/index.d.ts +98 -3
- package/dist/index.js +72 -2
- package/package.json +2 -1
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 —
|
|
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
|
|
15
|
-
`
|
|
16
|
-
|
|
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 "
|
|
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");
|
|
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.
|