@effected/schemastore 0.9.1 → 0.11.0
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/CanonicalJson.js +38 -3
- package/CatalogEntry.js +6 -2
- package/DocumentDiff.js +8 -20
- package/DocumentLint.js +47 -14
- package/README.md +10 -2
- package/SchemaPipeline.js +4 -2
- package/SchemaTarget.js +2 -1
- package/SchemaVersioning.js +41 -19
- package/SchemastoreConfig.js +183 -67
- package/StoreDocument.js +55 -3
- package/index.d.ts +276 -52
- package/index.js +2 -2
- package/package.json +1 -1
package/index.d.ts
CHANGED
|
@@ -94,6 +94,22 @@ export declare class CanonicalJson {
|
|
|
94
94
|
* primitive — synchronous callers can use that variant directly.
|
|
95
95
|
*/
|
|
96
96
|
static readonly serialize: (value: unknown, options?: CanonicalJsonOptions | undefined) => Effect.Effect<string, CanonicalJsonError, never>;
|
|
97
|
+
/**
|
|
98
|
+
* Content equality under the serializer's own semantics: two values are
|
|
99
|
+
* equal when they would parse to the same JSON document — object key
|
|
100
|
+
* order is a serialization detail and is ignored, array order is data
|
|
101
|
+
* and is not. `NaN` is never equal to itself (it is not JSON). The same
|
|
102
|
+
* reference compares `true` before any structural walk — so a cyclic
|
|
103
|
+
* value equals itself — and the comparison is total: two distinct
|
|
104
|
+
* cyclic or hostile-depth values report `false` at the stack guard
|
|
105
|
+
* rather than overflowing.
|
|
106
|
+
*
|
|
107
|
+
* This is the comparison `SchemaFile`'s write-if-changed and
|
|
108
|
+
* `DocumentDiff`'s leaf comparison already make, exported so a consumer
|
|
109
|
+
* writing its own JSON artifact (a catalog entry) can decide "unchanged"
|
|
110
|
+
* by the same rule instead of re-implementing it.
|
|
111
|
+
*/
|
|
112
|
+
static equals(left: unknown, right: unknown): boolean;
|
|
97
113
|
}
|
|
98
114
|
//#endregion
|
|
99
115
|
//#region src/DocumentDiff.d.ts
|
|
@@ -213,7 +229,10 @@ declare const UndeclaredAnnotationKeyError_base: Schema.Class<UndeclaredAnnotati
|
|
|
213
229
|
/**
|
|
214
230
|
* Indicates that a caller-supplied `includeAnnotationKey` admitted an
|
|
215
231
|
* annotation key outside the declared keyword families
|
|
216
|
-
* ({@link KeywordFamilies})
|
|
232
|
+
* ({@link KeywordFamilies}), or that a
|
|
233
|
+
* {@link StoreDocumentOptions.rootAnnotations} override names a key outside
|
|
234
|
+
* the admitted set (the standard annotation keywords plus the declared
|
|
235
|
+
* families).
|
|
217
236
|
*
|
|
218
237
|
* Raised by {@link StoreDocument.fromSchema}. This package emits
|
|
219
238
|
* SchemaStore-compatible documents only, so the declared families are the
|
|
@@ -224,7 +243,8 @@ declare const UndeclaredAnnotationKeyError_base: Schema.Class<UndeclaredAnnotati
|
|
|
224
243
|
*
|
|
225
244
|
* The predicate itself cannot be introspected, so the offending keys are
|
|
226
245
|
* the ones it actually admitted while the document was being generated: a
|
|
227
|
-
* key the source schema never annotates cannot appear here.
|
|
246
|
+
* key the source schema never annotates cannot appear here. Override keys,
|
|
247
|
+
* by contrast, are checked up front, before anything is generated.
|
|
228
248
|
*
|
|
229
249
|
* @public
|
|
230
250
|
*/
|
|
@@ -258,6 +278,39 @@ interface StoreDocumentOptions {
|
|
|
258
278
|
* `ToJsonSchemaOptions` passes through, and is best left unset.
|
|
259
279
|
*/
|
|
260
280
|
readonly jsonSchema?: Schema.ToJsonSchemaOptions;
|
|
281
|
+
/**
|
|
282
|
+
* Annotations merged onto the emitted document's root after assembly —
|
|
283
|
+
* the escape hatch for a generator-side annotation loss the source
|
|
284
|
+
* schema cannot express (a filtered field, or a root whose annotations
|
|
285
|
+
* core does not carry).
|
|
286
|
+
*
|
|
287
|
+
* Admitted keys are the standard JSON Schema annotation keywords
|
|
288
|
+
* (`title`, `description`, `$comment`, `default`, `examples`,
|
|
289
|
+
* `readOnly`, `writeOnly`, `contentMediaType`, `contentEncoding`) and
|
|
290
|
+
* the declared keyword families
|
|
291
|
+
* ({@link KeywordFamilies}); any other key fails the build with
|
|
292
|
+
* {@link UndeclaredAnnotationKeyError}, so the override cannot become a
|
|
293
|
+
* back door for assertion keywords. Override keys win over generated
|
|
294
|
+
* ones. The override is checked before generation, so when both this
|
|
295
|
+
* gate and the `includeAnnotationKey` gate would fire, the override's
|
|
296
|
+
* keys are the ones reported and the predicate's are not.
|
|
297
|
+
*
|
|
298
|
+
* Placement follows the assembled root's shape, in three cases:
|
|
299
|
+
*
|
|
300
|
+
* - An inline root (a `Struct`, a primitive) takes the annotations
|
|
301
|
+
* directly.
|
|
302
|
+
* - A bare local `$ref` root (the shape a `Schema.Class` root produces —
|
|
303
|
+
* `{ "$ref": "#/$defs/FooEncoded" }`) whose `$defs` entry has no
|
|
304
|
+
* other referent takes them on that entry instead: Draft-07
|
|
305
|
+
* validators ignore `$ref` siblings, so the root would carry them
|
|
306
|
+
* nowhere.
|
|
307
|
+
* - A bare local `$ref` root whose entry is shared — a recursive class,
|
|
308
|
+
* or one another definition also references — is replaced by
|
|
309
|
+
* `{ ...annotations, allOf: [{ "$ref": ... }] }`, so the document is
|
|
310
|
+
* annotated without every other occurrence of the type inheriting
|
|
311
|
+
* the root's title.
|
|
312
|
+
*/
|
|
313
|
+
readonly rootAnnotations?: Readonly<Record<string, unknown>>;
|
|
261
314
|
}
|
|
262
315
|
declare const StoreDocument_base: Schema.Class<StoreDocument, Schema.Struct<{
|
|
263
316
|
/** The meta-schema URL ({@link DRAFT_07_META_SCHEMA}). */
|
|
@@ -597,6 +650,15 @@ export declare const SchemaVersion: Schema.brand<Schema.String, "SchemaVersion">
|
|
|
597
650
|
* @public
|
|
598
651
|
*/
|
|
599
652
|
export type SchemaVersion = typeof SchemaVersion.Type;
|
|
653
|
+
/**
|
|
654
|
+
* Where a versioned document sits relative to its base: `flat` is
|
|
655
|
+
* `<name>-<version>.json` (the only shape SchemaStore serves), `versioned`
|
|
656
|
+
* nests it as `<version>/<name>-<version>.json`. An unversioned document is
|
|
657
|
+
* `<name>.json` under either.
|
|
658
|
+
*
|
|
659
|
+
* @public
|
|
660
|
+
*/
|
|
661
|
+
type SchemaLayout = "flat" | "versioned";
|
|
600
662
|
/**
|
|
601
663
|
* The `url`/`versions` half of a catalog entry, as assembled by
|
|
602
664
|
* {@link SchemaVersioning.catalogUrls}.
|
|
@@ -703,42 +765,58 @@ export declare class SchemaVersioning {
|
|
|
703
765
|
* the label and the ceiling rather than `SemVer.make`'s bare schema failure.
|
|
704
766
|
*/
|
|
705
767
|
static next(current: SchemaVersion, change: WriteChange): SchemaVersion;
|
|
768
|
+
/**
|
|
769
|
+
* Whether a name is a simple file base name — non-empty, no path
|
|
770
|
+
* separators, no whitespace — the rule every schema name is held to
|
|
771
|
+
* ({@link SchemaVersioning.fileName} throws on anything else; `defineConfig`
|
|
772
|
+
* rejects a schema key the same way). One predicate so the two cannot drift.
|
|
773
|
+
*/
|
|
774
|
+
static isSimpleName(name: string): boolean;
|
|
706
775
|
/**
|
|
707
776
|
* Derives the schema file name for a catalog name: `name.json`
|
|
708
|
-
* unversioned, `name-<version>.json` versioned
|
|
777
|
+
* unversioned, `name-<version>.json` versioned under the `"flat"`
|
|
778
|
+
* layout (the default and the only shape SchemaStore serves), or
|
|
779
|
+
* `<version>/name-<version>.json` under `"versioned"`.
|
|
709
780
|
*
|
|
710
781
|
* The name must be a simple file base name (no separators, no
|
|
711
782
|
* whitespace); anything else is a wiring mistake and throws.
|
|
712
783
|
*/
|
|
713
|
-
static fileName(name: string, version?: SchemaVersion): string;
|
|
784
|
+
static fileName(name: string, version?: SchemaVersion, layout?: SchemaLayout): string;
|
|
714
785
|
/**
|
|
715
786
|
* The canonical URL a schema file is hosted at: `baseUrl` joined with
|
|
716
787
|
* {@link SchemaVersioning.fileName}.
|
|
717
788
|
*/
|
|
718
|
-
static schemaUrl(baseUrl: string, name: string, version?: SchemaVersion): string;
|
|
789
|
+
static schemaUrl(baseUrl: string, name: string, version?: SchemaVersion, layout?: SchemaLayout): string;
|
|
719
790
|
/**
|
|
720
791
|
* Assembles the `url`/`versions` half of a catalog entry.
|
|
721
792
|
*
|
|
722
793
|
* Omitting `versions` selects the unversioned mode (`url` only,
|
|
723
794
|
* pointing at the plain `name.json`). Providing them selects the
|
|
724
795
|
* versioned mode: the `versions` map carries every label, and `url`
|
|
725
|
-
* points at
|
|
796
|
+
* points at `current` (default: the newest label under
|
|
797
|
+
* {@link SchemaVersioning.Order}). An **empty** `versions` array is
|
|
726
798
|
* a contradiction (versioned mode with no versions) and throws — pass
|
|
727
|
-
* `undefined` for the unversioned mode.
|
|
799
|
+
* `undefined` for the unversioned mode. `current`, when given, must
|
|
800
|
+
* compare equal under {@link SchemaVersioning.Order} to a member of
|
|
801
|
+
* `versions` or this throws; `url` is built from that member's own
|
|
802
|
+
* spelling (the `versions` map's key), not from the `current` argument
|
|
803
|
+
* verbatim — so a differently-spelled equivalent (`"1.2"` matching a
|
|
804
|
+
* `"1.2.0"` member) still points `url` at the same file the map does.
|
|
805
|
+
*
|
|
806
|
+
* `layout` (default `"flat"`) is forwarded to every URL derivation, so
|
|
807
|
+
* `"versioned"` nests every map value and `url` under its own version
|
|
808
|
+
* directory.
|
|
728
809
|
*
|
|
729
|
-
* Labels are inserted in ascending {@link SchemaVersioning.Order}
|
|
730
|
-
*
|
|
731
|
-
*
|
|
732
|
-
* `versions` map is not meaningful when such a label is present. A two-
|
|
733
|
-
* or three-component label is never integer-like and keeps insertion
|
|
734
|
-
* order through serialization. Deriving ordering from the labels
|
|
735
|
-
* themselves (as {@link SchemaVersioning.latest} does) is still the
|
|
736
|
-
* robust read.
|
|
810
|
+
* Labels are inserted in ascending {@link SchemaVersioning.Order}; see
|
|
811
|
+
* {@link CatalogUrls.versions} for why a bare-major key's serialized
|
|
812
|
+
* position is not meaningful.
|
|
737
813
|
*/
|
|
738
814
|
static catalogUrls(options: {
|
|
739
815
|
readonly baseUrl: string;
|
|
740
816
|
readonly name: string;
|
|
741
817
|
readonly versions?: ReadonlyArray<SchemaVersion>;
|
|
818
|
+
readonly layout?: SchemaLayout;
|
|
819
|
+
readonly current?: SchemaVersion;
|
|
742
820
|
}): CatalogUrls;
|
|
743
821
|
}
|
|
744
822
|
//#endregion
|
|
@@ -788,7 +866,9 @@ export declare class CatalogEntry extends CatalogEntry_base {
|
|
|
788
866
|
* Assembles an entry from a catalog identity plus
|
|
789
867
|
* {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
|
|
790
868
|
* versioned mode (the `versions` map and latest-pointing `url` are
|
|
791
|
-
* derived), omit it for the unversioned mode.
|
|
869
|
+
* derived), omit it for the unversioned mode. `layout` (default
|
|
870
|
+
* `"flat"`) and `current` (default: the newest label) are forwarded to
|
|
871
|
+
* {@link SchemaVersioning.catalogUrls} verbatim. Throws an `Error` naming
|
|
792
872
|
* both spellings when two labels compare equal under
|
|
793
873
|
* {@link SchemaVersioning.Order} (`1.2` and `1.2.0`): each would be its
|
|
794
874
|
* own key and URL for one document.
|
|
@@ -800,6 +880,8 @@ export declare class CatalogEntry extends CatalogEntry_base {
|
|
|
800
880
|
readonly baseUrl: string;
|
|
801
881
|
readonly fileBaseName?: string;
|
|
802
882
|
readonly versions?: ReadonlyArray<SchemaVersion>;
|
|
883
|
+
readonly layout?: SchemaLayout;
|
|
884
|
+
readonly current?: SchemaVersion;
|
|
803
885
|
}): CatalogEntry;
|
|
804
886
|
/**
|
|
805
887
|
* The fileMatch hygiene lint over this entry's patterns — pure shape
|
|
@@ -845,10 +927,18 @@ export declare class DocumentLintFinding extends DocumentLintFinding_base {}
|
|
|
845
927
|
* non-standard families ({@link KeywordFamilies}: `x-taplo*`, `x-tombi-*`,
|
|
846
928
|
* `x-intellij-*`, `x-ai-*` and the vscode set), which ajv strict mode would reject.
|
|
847
929
|
* - `DescriptionWithoutUrl` — advisory: SchemaStore's description
|
|
848
|
-
* convention ends the root description with a docs URL line.
|
|
849
|
-
*
|
|
850
|
-
*
|
|
851
|
-
*
|
|
930
|
+
* convention ends the root description with a docs URL line. Read from
|
|
931
|
+
* the root, or from the `$defs` entry a bare local `$ref` root names —
|
|
932
|
+
* where assembly places a root annotation.
|
|
933
|
+
*
|
|
934
|
+
* Tractable because the input is the bounded {@link StoreDocument} shape,
|
|
935
|
+
* not because assembly built it: the warning checks earn their keep on a
|
|
936
|
+
* document the pipeline did not build — hand-assembled through
|
|
937
|
+
* `StoreDocument.draft07`, or read back off disk. A local `$defs` pointer
|
|
938
|
+
* is decoded the way ajv decodes it, so no `$ref` into the pool that the
|
|
939
|
+
* engine gate resolves is reported `UnresolvedRef`; a `#/definitions/...`
|
|
940
|
+
* pointer stays a warning on purpose, since the pool lives under `$defs`.
|
|
941
|
+
* This is not a general JSON Schema validator.
|
|
852
942
|
*
|
|
853
943
|
* @public
|
|
854
944
|
*/
|
|
@@ -1068,6 +1158,12 @@ export interface SchemaTarget {
|
|
|
1068
1158
|
* `includeAnnotationKey` gate this option is also subject to.
|
|
1069
1159
|
*/
|
|
1070
1160
|
readonly jsonSchema?: Schema.ToJsonSchemaOptions;
|
|
1161
|
+
/**
|
|
1162
|
+
* Forwarded to {@link StoreDocumentOptions.rootAnnotations}; a
|
|
1163
|
+
* target-level field for the same self-describing reason as
|
|
1164
|
+
* `jsonSchema`.
|
|
1165
|
+
*/
|
|
1166
|
+
readonly rootAnnotations?: Readonly<Record<string, unknown>>;
|
|
1071
1167
|
}
|
|
1072
1168
|
/**
|
|
1073
1169
|
* Constructors for `SchemaTarget` values.
|
|
@@ -1087,6 +1183,7 @@ export declare class SchemaTarget {
|
|
|
1087
1183
|
readonly path: string;
|
|
1088
1184
|
readonly published?: boolean;
|
|
1089
1185
|
readonly jsonSchema?: Schema.ToJsonSchemaOptions;
|
|
1186
|
+
readonly rootAnnotations?: Readonly<Record<string, unknown>>;
|
|
1090
1187
|
}): SchemaTarget;
|
|
1091
1188
|
/**
|
|
1092
1189
|
* Builds a versioned target. `name` is **required** here: versioned
|
|
@@ -1103,6 +1200,7 @@ export declare class SchemaTarget {
|
|
|
1103
1200
|
readonly version: SchemaVersion | string;
|
|
1104
1201
|
readonly published?: boolean;
|
|
1105
1202
|
readonly jsonSchema?: Schema.ToJsonSchemaOptions;
|
|
1203
|
+
readonly rootAnnotations?: Readonly<Record<string, unknown>>;
|
|
1106
1204
|
}): SchemaTarget;
|
|
1107
1205
|
}
|
|
1108
1206
|
//#endregion
|
|
@@ -1566,42 +1664,144 @@ export declare class SchemaPipeline {
|
|
|
1566
1664
|
//#endregion
|
|
1567
1665
|
//#region src/SchemastoreConfig.d.ts
|
|
1568
1666
|
declare const ConfigBrand: unique symbol;
|
|
1667
|
+
/** The host SchemaStore-hosted documents declare in `$id`. @public */
|
|
1668
|
+
export declare const SCHEMASTORE_ID_BASE = "https://json.schemastore.org";
|
|
1669
|
+
/** The host SchemaStore's `catalog.json` points `url` at. @public */
|
|
1670
|
+
export declare const SCHEMASTORE_CATALOG_BASE = "https://www.schemastore.org";
|
|
1569
1671
|
/**
|
|
1570
|
-
*
|
|
1571
|
-
* `
|
|
1572
|
-
*
|
|
1573
|
-
*
|
|
1672
|
+
* The SchemaStore `catalog.json` fields a schema entry declares, minus
|
|
1673
|
+
* `url`/`versions` — those are derived from the entry's `baseUrl`, `layout`
|
|
1674
|
+
* and `versions`/`current` by {@link defineConfig}, so they cannot disagree
|
|
1675
|
+
* with the schema's own identity.
|
|
1574
1676
|
*
|
|
1575
1677
|
* @public
|
|
1576
1678
|
*/
|
|
1577
|
-
interface
|
|
1578
|
-
|
|
1679
|
+
interface CatalogInput {
|
|
1680
|
+
/** The catalog description. */
|
|
1579
1681
|
readonly description: string;
|
|
1682
|
+
/** Glob patterns editors match files against; must be non-empty. */
|
|
1580
1683
|
readonly fileMatch: ReadonlyArray<string>;
|
|
1581
|
-
readonly baseUrl: string;
|
|
1582
|
-
/** Where to write the assembled entry; relative paths are resolved by the loader against the config file's directory. */
|
|
1583
|
-
readonly path: string;
|
|
1584
1684
|
}
|
|
1585
1685
|
/**
|
|
1586
|
-
*
|
|
1587
|
-
*
|
|
1686
|
+
* One schema a `schemastore.config.ts` declares, keyed by its own file base
|
|
1687
|
+
* name in {@link SchemastoreConfigInput.schemas}. `$id`, the write `path` and
|
|
1688
|
+
* every catalog URL are derived from `outputDir`, `baseUrl` (this entry's, or
|
|
1689
|
+
* the config's default) and `layout` — never spelled out by hand.
|
|
1690
|
+
*
|
|
1691
|
+
* @public
|
|
1692
|
+
*/
|
|
1693
|
+
interface SchemaEntryInput {
|
|
1694
|
+
/** The Effect Schema source the document is generated from. */
|
|
1695
|
+
readonly schema: Schema.Constraint;
|
|
1696
|
+
/**
|
|
1697
|
+
* Every version label this schema advertises. Omit for an unversioned
|
|
1698
|
+
* schema (`<name>.json`). An empty array is rejected — omit the field
|
|
1699
|
+
* instead. Two labels that compare equal under
|
|
1700
|
+
* {@link SchemaVersioning.Order} (`"1.2"` and `"1.2.0"`) are rejected as
|
|
1701
|
+
* one version spelled twice.
|
|
1702
|
+
*/
|
|
1703
|
+
readonly versions?: ReadonlyArray<string>;
|
|
1704
|
+
/**
|
|
1705
|
+
* Which of `versions` is the one generated at this entry's `path`/`$id`;
|
|
1706
|
+
* the rest become {@link ResolvedSchema.frozen} files the CLI verifies
|
|
1707
|
+
* but does not regenerate. Defaults to the newest label under
|
|
1708
|
+
* {@link SchemaVersioning.Order}. Requires `versions`, and must name one
|
|
1709
|
+
* of them.
|
|
1710
|
+
*/
|
|
1711
|
+
readonly current?: string;
|
|
1712
|
+
/**
|
|
1713
|
+
* Whether a consumer already depends on this document at this label —
|
|
1714
|
+
* forwarded to {@link (SchemaTarget:class).(make:1)}. Defaults to `false`.
|
|
1715
|
+
*/
|
|
1716
|
+
readonly published?: boolean;
|
|
1717
|
+
/**
|
|
1718
|
+
* Where this schema is hosted: the literal `"schemastore"` (the only
|
|
1719
|
+
* value that expands `$id` to {@link SCHEMASTORE_ID_BASE} and the catalog
|
|
1720
|
+
* URL to {@link SCHEMASTORE_CATALOG_BASE}, and forces the `"flat"`
|
|
1721
|
+
* layout) or an `https://` URL used as ONE base for both `$id` and the
|
|
1722
|
+
* catalog URL. Falls back to {@link SchemastoreConfigInput.baseUrl} when
|
|
1723
|
+
* omitted; an entry with neither is rejected.
|
|
1724
|
+
*/
|
|
1725
|
+
readonly baseUrl?: string;
|
|
1726
|
+
/**
|
|
1727
|
+
* How a versioned document's path/URL nests relative to its base — see
|
|
1728
|
+
* {@link SchemaLayout}. Defaults to `"versioned"` for a custom `baseUrl`,
|
|
1729
|
+
* and is rejected outright under `baseUrl: "schemastore"`, which serves
|
|
1730
|
+
* only the flat layout.
|
|
1731
|
+
*/
|
|
1732
|
+
readonly layout?: SchemaLayout;
|
|
1733
|
+
/** Overrides {@link SchemastoreConfigInput.drift} for this schema. */
|
|
1734
|
+
readonly drift?: DriftTolerance;
|
|
1735
|
+
/**
|
|
1736
|
+
* The catalog entry to assemble for this schema. Required under
|
|
1737
|
+
* `baseUrl: "schemastore"` (every SchemaStore-hosted document is
|
|
1738
|
+
* cataloged); optional under a custom host.
|
|
1739
|
+
*/
|
|
1740
|
+
readonly catalog?: CatalogInput;
|
|
1741
|
+
/** Forwarded to {@link (SchemaTarget:class).(make:1)}'s `jsonSchema`. */
|
|
1742
|
+
readonly jsonSchema?: Schema.ToJsonSchemaOptions;
|
|
1743
|
+
/** Forwarded to {@link (SchemaTarget:class).(make:1)}'s `rootAnnotations`. */
|
|
1744
|
+
readonly rootAnnotations?: Readonly<Record<string, unknown>>;
|
|
1745
|
+
}
|
|
1746
|
+
/**
|
|
1747
|
+
* What a `schemastore.config.ts` hands to {@link defineConfig}: a directory
|
|
1748
|
+
* every derived path is written under, top-level defaults for `baseUrl` and
|
|
1749
|
+
* `drift`, and the keyed set of schemas to derive.
|
|
1588
1750
|
*
|
|
1589
1751
|
* @public
|
|
1590
1752
|
*/
|
|
1591
1753
|
interface SchemastoreConfigInput {
|
|
1592
|
-
|
|
1593
|
-
readonly
|
|
1594
|
-
|
|
1754
|
+
/** The directory every derived `path` is written under; a trailing slash is trimmed. */
|
|
1755
|
+
readonly outputDir: string;
|
|
1756
|
+
/** The default {@link SchemaEntryInput.baseUrl} for an entry that declares none. */
|
|
1757
|
+
readonly baseUrl?: string;
|
|
1758
|
+
/** The default {@link SchemaEntryInput.drift} for an entry that declares none. Defaults to `"semantic"`. */
|
|
1759
|
+
readonly drift?: DriftTolerance;
|
|
1760
|
+
/** What a build does when it finds drift. Defaults to `"error"`. */
|
|
1761
|
+
readonly onDrift?: OnDrift;
|
|
1762
|
+
/** Where the assembled catalog is written. Defaults to `<outputDir>/catalog.json`. */
|
|
1763
|
+
readonly catalogPath?: string;
|
|
1764
|
+
/**
|
|
1765
|
+
* The schemas to derive, keyed by file base name — the key IS the
|
|
1766
|
+
* `name` every derived path and URL is built from, so it must be a
|
|
1767
|
+
* simple file base name (no separators, no whitespace).
|
|
1768
|
+
*/
|
|
1769
|
+
readonly schemas: Readonly<Record<string, SchemaEntryInput>>;
|
|
1595
1770
|
}
|
|
1596
1771
|
/**
|
|
1597
|
-
*
|
|
1598
|
-
*
|
|
1772
|
+
* One version of a schema that is advertised (via `versions`) but not the
|
|
1773
|
+
* one currently generated — a file the CLI verifies exists on disk before
|
|
1774
|
+
* any write (existence only — content is never compared), never
|
|
1775
|
+
* regenerates.
|
|
1599
1776
|
*
|
|
1600
1777
|
* @public
|
|
1601
1778
|
*/
|
|
1602
|
-
interface
|
|
1603
|
-
|
|
1604
|
-
readonly
|
|
1779
|
+
interface FrozenVersion {
|
|
1780
|
+
/** The frozen version label. */
|
|
1781
|
+
readonly version: SchemaVersion;
|
|
1782
|
+
/** The path the frozen file lives at. */
|
|
1783
|
+
readonly path: string;
|
|
1784
|
+
/** The catalog URL the frozen file is hosted at. */
|
|
1785
|
+
readonly url: string;
|
|
1786
|
+
}
|
|
1787
|
+
/**
|
|
1788
|
+
* One `defineConfig` schema entry, resolved: the {@link (SchemaTarget:interface)} to
|
|
1789
|
+
* generate, its frozen predecessor versions, its effective drift tolerance,
|
|
1790
|
+
* and its assembled catalog entry, if any.
|
|
1791
|
+
*
|
|
1792
|
+
* @public
|
|
1793
|
+
*/
|
|
1794
|
+
interface ResolvedSchema {
|
|
1795
|
+
/** The schema's key in {@link SchemastoreConfigInput.schemas}. */
|
|
1796
|
+
readonly name: string;
|
|
1797
|
+
/** The target to generate at the current version (or the sole, unversioned target). */
|
|
1798
|
+
readonly target: SchemaTarget;
|
|
1799
|
+
/** Every OTHER advertised version, as a frozen file to verify. */
|
|
1800
|
+
readonly frozen: ReadonlyArray<FrozenVersion>;
|
|
1801
|
+
/** This entry's effective drift tolerance, after falling back to the config default. */
|
|
1802
|
+
readonly drift: DriftTolerance;
|
|
1803
|
+
/** The assembled catalog entry, when {@link SchemaEntryInput.catalog} was given. */
|
|
1804
|
+
readonly catalog?: CatalogEntry;
|
|
1605
1805
|
}
|
|
1606
1806
|
/**
|
|
1607
1807
|
* The validated, defaults-filled config {@link defineConfig} answers and the
|
|
@@ -1611,23 +1811,47 @@ interface CatalogTarget {
|
|
|
1611
1811
|
*/
|
|
1612
1812
|
interface SchemastoreConfig {
|
|
1613
1813
|
readonly [ConfigBrand]: true;
|
|
1614
|
-
|
|
1615
|
-
readonly
|
|
1616
|
-
|
|
1814
|
+
/** The directory every derived `path` is written under, trailing slash trimmed. */
|
|
1815
|
+
readonly outputDir: string;
|
|
1816
|
+
/** What a build does when it finds drift. */
|
|
1817
|
+
readonly onDrift: OnDrift;
|
|
1818
|
+
/** Where the assembled catalog is written. */
|
|
1819
|
+
readonly catalogPath: string;
|
|
1820
|
+
/** Every schema, resolved. */
|
|
1821
|
+
readonly schemas: ReadonlyArray<ResolvedSchema>;
|
|
1617
1822
|
}
|
|
1618
1823
|
/**
|
|
1619
1824
|
* Validate and assemble a `schemastore.config.ts` value.
|
|
1620
1825
|
*
|
|
1621
1826
|
* @remarks
|
|
1622
|
-
* Pure: no IO, no Effect.
|
|
1623
|
-
*
|
|
1624
|
-
*
|
|
1625
|
-
*
|
|
1626
|
-
*
|
|
1627
|
-
*
|
|
1628
|
-
*
|
|
1629
|
-
*
|
|
1630
|
-
*
|
|
1827
|
+
* Pure: no IO, no Effect. `$id`, the write `path` and every catalog URL are
|
|
1828
|
+
* derived from ONE layout (`outputDir`, `baseUrl` and `layout`) so they
|
|
1829
|
+
* cannot disagree with each other. `versions` names every label a schema
|
|
1830
|
+
* advertises; `current` (default: the newest under
|
|
1831
|
+
* {@link SchemaVersioning.Order}) is the one generated at `target`, and every
|
|
1832
|
+
* other label becomes a {@link FrozenVersion} the CLI verifies but does not
|
|
1833
|
+
* regenerate. `baseUrl: "schemastore"` expands to
|
|
1834
|
+
* {@link SCHEMASTORE_ID_BASE} for `$id` and {@link SCHEMASTORE_CATALOG_BASE}
|
|
1835
|
+
* for the catalog URL, forcing the `"flat"` layout; any other `baseUrl` is
|
|
1836
|
+
* used as one base for both, defaulting to the `"versioned"` layout.
|
|
1837
|
+
*
|
|
1838
|
+
* Throws a plain `Error` (never a raw `TypeError`) naming the offending
|
|
1839
|
+
* schema on: a non-object `input`; an empty `schemas` record; a
|
|
1840
|
+
* missing/empty `outputDir`; a schema key that is not a simple file base
|
|
1841
|
+
* name; a schema whose `schema` is not an Effect Schema; a schema with no
|
|
1842
|
+
* `baseUrl` anywhere, or a `baseUrl` that is not a string; a `baseUrl` that
|
|
1843
|
+
* is neither `"schemastore"` nor an `https://` URL; a `versions` that is not
|
|
1844
|
+
* an array, or an empty `versions` array; a version label (or `current`)
|
|
1845
|
+
* that is not a string, or an otherwise invalid version label; two labels
|
|
1846
|
+
* spelling the same version; `current` given without `versions`, or naming
|
|
1847
|
+
* one not among them; a non-boolean `published`; `layout` declared under
|
|
1848
|
+
* `baseUrl: "schemastore"`; a missing `catalog` under
|
|
1849
|
+
* `baseUrl: "schemastore"`, or one with an empty `fileMatch`; an invalid
|
|
1850
|
+
* `drift` or top-level `onDrift`; and an output path (a target, a frozen
|
|
1851
|
+
* file, or the catalog path) declared twice, compared after a lexical
|
|
1852
|
+
* normalisation (`./`, `..`, trailing `/`) — the CLI's loader re-checks on
|
|
1853
|
+
* the resolved absolute paths. Branding the result lets a loader recognise a
|
|
1854
|
+
* config module's default export via {@link isSchemastoreConfig}.
|
|
1631
1855
|
*
|
|
1632
1856
|
* @public
|
|
1633
1857
|
*/
|
|
@@ -1640,5 +1864,5 @@ export declare const defineConfig: (input: SchemastoreConfigInput) => Schemastor
|
|
|
1640
1864
|
*/
|
|
1641
1865
|
export declare const isSchemastoreConfig: (value: unknown) => value is SchemastoreConfig;
|
|
1642
1866
|
//#endregion
|
|
1643
|
-
export type { CanonicalJsonError, CanonicalJsonOptions,
|
|
1867
|
+
export type { CanonicalJsonError, CanonicalJsonOptions, CatalogInput, CatalogUrls, CheckResult, ContractChangePolicy, DriftOptions, DriftTolerance, DriftVerdict, FrozenVersion, OnDrift, PipelineCheckResult, PipelineResult, ResolvedSchema, SchemaChange, SchemaEntryInput, SchemaFileShape, SchemaLayout, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, SchemastoreConfig, SchemastoreConfigInput, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
|
|
1644
1868
|
//# sourceMappingURL=index.d.ts.map
|
package/index.js
CHANGED
|
@@ -9,7 +9,7 @@ import { SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWri
|
|
|
9
9
|
import { SchemaValidator, SchemaValidatorError, ValidationFinding } from "./SchemaValidator.js";
|
|
10
10
|
import { DRAFT_07_META_SCHEMA, SchemaConversionError, StoreDocument, UndeclaredAnnotationKeyError } from "./StoreDocument.js";
|
|
11
11
|
import { ContractChangeTarget, PipelineFinding, SchemaContractChangeError, SchemaGateError, SchemaPipeline } from "./SchemaPipeline.js";
|
|
12
|
-
import { defineConfig, isSchemastoreConfig } from "./SchemastoreConfig.js";
|
|
13
12
|
import { SchemaTarget } from "./SchemaTarget.js";
|
|
13
|
+
import { SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, defineConfig, isSchemastoreConfig } from "./SchemastoreConfig.js";
|
|
14
14
|
|
|
15
|
-
export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, DriftPolicy, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding, defineConfig, isSchemastoreConfig };
|
|
15
|
+
export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, DriftPolicy, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding, defineConfig, isSchemastoreConfig };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@effected/schemastore",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Build, validate, version and publish SchemaStore-shaped Draft-07 JSON Schema documents from Effect Schema sources: document assembly, ajv strict-mode validation, structural lints, catalog entries, canonical JSON and a content-comparing emit pipeline.",
|
|
6
6
|
"keywords": [
|