cedar-model-typescript-library 1.0.3 → 1.0.4

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.
Files changed (2) hide show
  1. package/README.md +117 -10
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,20 +1,127 @@
1
- # CEDAR Model Typescript Library
1
+ # CEDAR Model TypeScript Library
2
2
 
3
- A library to work with CEDAR templates and instances - implemented in TypeScript
3
+ [![Test](https://github.com/metadatacenter/cedar-model-typescript-library/actions/workflows/test.yml/badge.svg?branch=develop)](https://github.com/metadatacenter/cedar-model-typescript-library/actions/workflows/test.yml)
4
4
 
5
- ## Install
5
+ The CEDAR Model TypeScript Library is a TypeScript implementation of the
6
+ [CEDAR](https://metadatacenter.org/) artifact model. It provides typed models,
7
+ builders, readers, writers, and validators for CEDAR templates, elements, fields,
8
+ and metadata instances.
9
+
10
+ The library reads and writes the JSON, JSON-LD, and YAML representations used by
11
+ CEDAR. Applications can use the same model to construct artifacts, parse existing
12
+ artifacts, validate metadata instances, and translate between serializations.
13
+
14
+ For an introduction to the API and examples covering fields, elements, templates,
15
+ instances, readers, and writers, see the
16
+ [CEDAR Model TypeScript Library documentation](https://metadatacenter.readthedocs.io/en/latest/developer-guide/cedar-model-typescript-library/).
17
+
18
+ This README covers installing, building, and testing the library.
19
+
20
+ ## Installing the Library
21
+
22
+ Releases are published to npmjs.org as
23
+ [`cedar-model-typescript-library`](https://www.npmjs.com/package/cedar-model-typescript-library):
6
24
 
7
25
  ```shell
8
26
  npm install cedar-model-typescript-library
9
27
  ```
10
28
 
11
- ## YAML scalar style
29
+ The package includes CommonJS and ES module bundles together with TypeScript
30
+ declarations. Import its public API from the package entry point:
31
+
32
+ ```typescript
33
+ import {
34
+ CedarReaders,
35
+ CedarWriters,
36
+ JsonTemplateReaderResult,
37
+ Template,
38
+ } from 'cedar-model-typescript-library';
39
+
40
+ export function jsonTemplateToYaml(templateJson: string): string {
41
+ const result: JsonTemplateReaderResult = CedarReaders
42
+ .json()
43
+ .getStrict()
44
+ .getTemplateReader()
45
+ .readFromString(templateJson);
46
+
47
+ const errorCount = result.parsingResult.getBlueprintComparisonErrorCount();
48
+ if (errorCount > 0) {
49
+ throw new Error(`Template contains ${errorCount} parsing errors`);
50
+ }
51
+
52
+ const template: Template = result.template;
53
+
54
+ return CedarWriters
55
+ .yaml()
56
+ .getStrict()
57
+ .getTemplateWriter()
58
+ .getAsYamlString(template);
59
+ }
60
+ ```
61
+
62
+ Reader results also contain a parsing report. Applications that accept external
63
+ artifacts should inspect its errors and warnings before using the parsed artifact.
64
+
65
+ The [companion demo repository](https://github.com/metadatacenter/cedar-model-typescript-library-demo)
66
+ contains additional runnable examples.
67
+
68
+ ## Building
69
+
70
+ Use Node 24.19.0, which `.nvmrc` and CI both specify:
71
+
72
+ ```shell
73
+ nvm use
74
+ npm ci
75
+ npm run build
76
+ ```
77
+
78
+ The build writes the publishable package to `dist/`. It contains the CommonJS and
79
+ ES module bundles, source maps, TypeScript declarations, package manifest,
80
+ license, and this README.
81
+
82
+ For local development, rebuild when source files change:
83
+
84
+ ```shell
85
+ npm run build:watch
86
+ ```
87
+
88
+ To make the built package available to a local consumer through npm linking:
89
+
90
+ ```shell
91
+ npm run build
92
+ npm run link
93
+ ```
94
+
95
+ Then run `npm link cedar-model-typescript-library` in the consuming project.
96
+
97
+ ## Testing
98
+
99
+ Run the same checks exercised by continuous integration:
100
+
101
+ ```shell
102
+ npm run lint
103
+ npm run typecheck
104
+ npm run test:coverage
105
+ npm run parity:yaml
106
+ npm run parity:json
107
+ npm run test:package
108
+ ```
109
+
110
+ The unit suite covers the model and serialization behavior. The parity gates
111
+ compare the TypeScript library with the Java CEDAR Artifact Library over the
112
+ vendored JSON and YAML corpora.
113
+
114
+ `npm run test:package` builds the package that would be published, packs and
115
+ installs it into an isolated consumer, and exercises its CommonJS bundle, ES
116
+ module bundle, and TypeScript declarations.
117
+
118
+ ## Releasing
12
119
 
13
- Canonical YAML leaves values plain only for `type`, `modelVersion`, `status`, `version`, `datatype`,
14
- `action`, `granularity`, `termType`, and `inputTimeFormat`, and only when the value belongs to that
15
- field's CEDAR-owned vocabulary. IRIs, timestamps, external vocabularies, and user-authored strings
16
- remain double-quoted. The Java artifact library applies and tests the same policy.
120
+ Release preparation and publication are documented in
121
+ [RELEASING.md](https://github.com/metadatacenter/cedar-model-typescript-library/blob/main/RELEASING.md).
122
+ The release command publishes `dist/`, not the repository root.
17
123
 
18
- ## See it in action
124
+ ## License
19
125
 
20
- Check out the README at the companion [demo repo](https://github.com/metadatacenter/cedar-model-typescript-library-demo)
126
+ The CEDAR Model TypeScript Library is released under the
127
+ [BSD 2-Clause License](https://github.com/metadatacenter/cedar-model-typescript-library/blob/main/license.txt).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "cedar-model-typescript-library",
3
- "version": "1.0.3",
4
- "description": "CEDAR Model Typescript Library - a library to work with fields, elements, templates and instances implemented in TypeScript",
3
+ "version": "1.0.4",
4
+ "description": "TypeScript models, builders, readers, writers, and validators for CEDAR metadata artifacts",
5
5
  "main": "index.js",
6
6
  "module": "index.esm.js",
7
7
  "types": "index.d.ts",