@effected/schemastore 0.11.0 → 0.13.0

package/SchemaVersioning.js

@@ -194,23 +194,27 @@ var SchemaVersioning = class SchemaVersioning {
 	* Derives the schema file name for a catalog name: `name.json`
 	* unversioned, `name-<version>.json` versioned under the `"flat"`
 	* layout (the default and the only shape SchemaStore serves), or
-	* `<version>/name-<version>.json` under `"versioned"`.
+	* `<version>/name-<version>.json` under `"versioned"` — `<version>/name.json`
+	* when `appendVersion` is `false`, which only the versioned layout can
+	* carry (under `"flat"` two versions would share one file name, so that
+	* combination throws).
 	*
 	* The name must be a simple file base name (no separators, no
 	* whitespace); anything else is a wiring mistake and throws.
 	*/
-	static fileName(name, version, layout = "flat") {
+	static fileName(name, version, layout = "flat", appendVersion = true) {
 		assertSimpleName(name);
+		if (!appendVersion && layout !== "versioned") throw new Error(`appendVersion: false requires the "versioned" layout; under "${layout}" every version of "${name}" would share one file name`);
 		if (version === void 0) return `${name}.json`;
-		const file = `${name}-${version}.json`;
+		const file = appendVersion ? `${name}-${version}.json` : `${name}.json`;
 		return layout === "versioned" ? `${version}/${file}` : file;
 	}
 	/**
 	* The canonical URL a schema file is hosted at: `baseUrl` joined with
 	* {@link SchemaVersioning.fileName}.
 	*/
-	static schemaUrl(baseUrl, name, version, layout = "flat") {
-		return joinUrl(baseUrl, SchemaVersioning.fileName(name, version, layout));
+	static schemaUrl(baseUrl, name, version, layout = "flat", appendVersion = true) {
+		return joinUrl(baseUrl, SchemaVersioning.fileName(name, version, layout, appendVersion));
 	}
 	/**
 	* Assembles the `url`/`versions` half of a catalog entry.
@@ -228,9 +232,10 @@ var SchemaVersioning = class SchemaVersioning {
 	* verbatim — so a differently-spelled equivalent (`"1.2"` matching a
 	* `"1.2.0"` member) still points `url` at the same file the map does.
 	*
-	* `layout` (default `"flat"`) is forwarded to every URL derivation, so
-	* `"versioned"` nests every map value and `url` under its own version
-	* directory.
+	* `layout` (default `"flat"`) and `appendVersion` (default `true`) are
+	* forwarded to every URL derivation, so `"versioned"` nests every map
+	* value and `url` under its own version directory, with or without the
+	* `-<version>` file suffix.
 	*
 	* Labels are inserted in ascending {@link SchemaVersioning.Order}; see
 	* {@link CatalogUrls.versions} for why a bare-major key's serialized
@@ -239,17 +244,18 @@ var SchemaVersioning = class SchemaVersioning {
 	static catalogUrls(options) {
 		const { baseUrl, name, versions } = options;
 		const layout = options.layout ?? "flat";
-		if (versions === void 0) return { url: SchemaVersioning.schemaUrl(baseUrl, name, void 0, layout) };
+		const appendVersion = options.appendVersion ?? true;
+		if (versions === void 0) return { url: SchemaVersioning.schemaUrl(baseUrl, name, void 0, layout, appendVersion) };
 		if (versions.length === 0) throw new Error(`catalogUrls received an empty versions array for "${name}": pass undefined for the unversioned mode`);
 		const ascending = [...versions].sort(SchemaVersioning.Order);
 		const map = {};
-		for (const version of ascending) map[version] = SchemaVersioning.schemaUrl(baseUrl, name, version, layout);
+		for (const version of ascending) map[version] = SchemaVersioning.schemaUrl(baseUrl, name, version, layout, appendVersion);
 		const newest = ascending[ascending.length - 1];
 		const requested = options.current ?? newest;
 		const current = ascending.find((v) => SchemaVersioning.Order(v, requested) === 0);
 		if (current === void 0) throw new Error(`catalogUrls: current "${requested}" is not one of the versions of "${name}"`);
 		return {
-			url: SchemaVersioning.schemaUrl(baseUrl, name, current, layout),
+			url: SchemaVersioning.schemaUrl(baseUrl, name, current, layout, appendVersion),
 			versions: map
 		};
 	}

package/SchemastoreConfig.js

@@ -1,22 +1,12 @@
 import { SchemaVersioning } from "./SchemaVersioning.js";
 import { CatalogEntry } from "./CatalogEntry.js";
 import { DriftPolicy } from "./DriftPolicy.js";
+import { HostedSchema } from "./HostedSchema.js";
 import { SchemaTarget } from "./SchemaTarget.js";
-import { Option, Predicate, Result, Schema } from "effect";
+import { Predicate, Result, Schema } from "effect";
 
 //#region src/SchemastoreConfig.ts
 const ConfigBrand = Symbol.for("@effected/schemastore/SchemastoreConfig");
-/** The host SchemaStore-hosted documents declare in `$id`. @public */
-const SCHEMASTORE_ID_BASE = "https://json.schemastore.org";
-/** The host SchemaStore's `catalog.json` points `url` at. @public */
-const SCHEMASTORE_CATALOG_BASE = "https://www.schemastore.org";
-const DRIFT_TOLERANCES = [
-	"strict",
-	"semantic",
-	"allow"
-];
-const ON_DRIFT = ["error", "warn"];
-const LAYOUTS = ["flat", "versioned"];
 const fail = (message) => {
 	throw new Error(`defineConfig: ${message}`);
 };
@@ -25,121 +15,130 @@ const trimSlashes = (dir) => {
 	while (end > 1 && dir.charCodeAt(end - 1) === 47) end -= 1;
 	return dir.slice(0, end);
 };
-const resolveHosting = (name, baseUrl, layout) => {
-	if (baseUrl === void 0) return fail(`schema "${name}" has no baseUrl and the config declares no default`);
-	if (typeof baseUrl !== "string") return fail(`schema "${name}" has a baseUrl that is not a string`);
-	if (baseUrl.length === 0) return fail(`schema "${name}" has no baseUrl and the config declares no default`);
-	if (layout !== void 0 && !LAYOUTS.includes(layout)) return fail(`schema "${name}" has an invalid layout "${String(layout)}"; expected "flat" or "versioned"`);
-	if (baseUrl === "schemastore") {
-		if (layout !== void 0) return fail(`schema "${name}" declares layout "${layout}" under baseUrl "schemastore", which serves only the flat layout`);
-		return {
-			idBase: SCHEMASTORE_ID_BASE,
-			catalogBase: SCHEMASTORE_CATALOG_BASE,
-			layout: "flat"
-		};
-	}
-	if (!baseUrl.startsWith("https://") || baseUrl.length === 8) return fail(`schema "${name}" has baseUrl "${baseUrl}"; expected "schemastore" or an https:// URL`);
-	return {
-		idBase: baseUrl,
-		catalogBase: baseUrl,
-		layout: layout ?? "versioned"
-	};
-};
-const parseLabel = (name, label) => {
-	if (typeof label !== "string") return fail(`schema "${name}" has a version label that is not a string: ${String(label)}`);
-	return Result.getOrThrowWith(SchemaVersioning.parseResult(label), (error) => /* @__PURE__ */ new Error(`defineConfig: schema "${name}" has an invalid version label "${label}": ${error.message}`));
+const members = (record) => Object.keys(record);
+const DriftToleranceInput = Schema.Literals(members({
+	strict: null,
+	semantic: null,
+	allow: null
+}));
+const OnDriftInput = Schema.Literals(members({
+	error: null,
+	warn: null
+}));
+const LayoutInput = Schema.Literals(members({
+	flat: null,
+	versioned: null
+}));
+const EffectSchemaInput = Schema.declare((u) => Schema.isSchema(u), { expected: "an Effect Schema" });
+const OptionsInput = Schema.declare((u) => Predicate.isObject(u), { expected: "an object" });
+const CatalogBlockInput = Schema.Struct({
+	description: Schema.String,
+	fileMatch: Schema.NonEmptyArray(Schema.String)
+});
+const EntryInput = Schema.Struct({
+	schema: EffectSchemaInput,
+	hosted: Schema.optionalKey(Schema.instanceOf(HostedSchema, { expected: "a HostedSchema" })),
+	versions: Schema.optionalKey(Schema.Array(Schema.String)),
+	current: Schema.optionalKey(Schema.String),
+	published: Schema.optionalKey(Schema.Boolean),
+	baseUrl: Schema.optionalKey(Schema.String),
+	layout: Schema.optionalKey(LayoutInput),
+	appendVersion: Schema.optionalKey(Schema.Boolean),
+	drift: Schema.optionalKey(DriftToleranceInput),
+	catalog: Schema.optionalKey(CatalogBlockInput),
+	jsonSchema: Schema.optionalKey(OptionsInput),
+	rootAnnotations: Schema.optionalKey(OptionsInput)
+});
+const ConfigInput = Schema.Struct({
+	outputDir: Schema.NonEmptyString,
+	baseUrl: Schema.optionalKey(Schema.String),
+	drift: Schema.optionalKey(DriftToleranceInput),
+	onDrift: Schema.optionalKey(OnDriftInput),
+	catalogPath: Schema.optionalKey(Schema.NonEmptyString),
+	schemas: Schema.Record(Schema.String, Schema.Unknown)
+});
+const DECODE_OPTIONS = {
+	onExcessProperty: "error",
+	errors: "all"
 };
-const resolveVersions = (name, entry) => {
-	if (entry.versions === void 0) {
-		if (entry.current !== void 0) return fail(`schema "${name}" declares current "${entry.current}" without versions`);
-		return;
-	}
-	if (!Array.isArray(entry.versions)) return fail(`schema "${name}" declares versions that is not an array`);
-	if (entry.versions.length === 0) return fail(`schema "${name}" declares versions as an empty array; omit versions for an unversioned schema`);
-	const versions = [];
-	for (const label of entry.versions) {
-		const version = parseLabel(name, label);
-		const duplicate = versions.find((v) => SchemaVersioning.Order(v, version) === 0);
-		if (duplicate !== void 0) return fail(`schema "${name}" declares the same version twice, as "${duplicate}" and "${version}"`);
-		versions.push(version);
+const withoutUndefined = (input) => Predicate.isObject(input) && !Array.isArray(input) ? Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0)) : input;
+const decodeOrThrow = (schema, input, prefix) => Result.getOrThrowWith(Schema.decodeUnknownResult(schema)(input, DECODE_OPTIONS), (error) => /* @__PURE__ */ new Error(`defineConfig: ${prefix}${error.message.replace(/\n\s*/g, " ")}`));
+const resolveIdentity = (name, entry, defaultBaseUrl) => {
+	if (entry.hosted !== void 0) {
+		if (entry.hosted.name !== name) return fail(`schema "${name}" is keyed differently from its hosted identity "${entry.hosted.name}"`);
+		const spelled = [
+			"baseUrl",
+			"versions",
+			"current",
+			"layout",
+			"appendVersion"
+		].filter((key) => entry[key] !== void 0);
+		if (spelled.length > 0) return fail(`schema "${name}" declares ${spelled.map((key) => `"${key}"`).join(", ")} beside hosted; the hosted identity owns them`);
+		return entry.hosted;
 	}
-	const newest = Option.getOrThrow(SchemaVersioning.latest(versions));
-	if (entry.current === void 0) return {
-		versions,
-		current: newest
-	};
-	const current = parseLabel(name, entry.current);
-	const match = versions.find((v) => SchemaVersioning.Order(v, current) === 0);
-	if (match === void 0) return fail(`schema "${name}" declares current "${entry.current}" which is not one of its versions`);
-	return {
-		versions,
-		current: match
-	};
-};
-const isDriftTolerance = (value) => DRIFT_TOLERANCES.includes(value);
-const resolveConfigDrift = (value) => {
-	if (value === void 0) return DriftPolicy.defaults.policy;
-	return isDriftTolerance(value) ? value : fail(`config has an invalid drift tolerance "${String(value)}"`);
-};
-const resolveSchemaDrift = (name, value, fallback) => {
-	if (value === void 0) return fallback;
-	return isDriftTolerance(value) ? value : fail(`schema "${name}" has an invalid drift tolerance "${String(value)}"`);
+	const baseUrl = entry.baseUrl ?? defaultBaseUrl;
+	if (baseUrl === void 0) return fail(`schema "${name}" has no baseUrl and the config declares no default`);
+	const decoded = Schema.decodeUnknownResult(HostedSchema)(withoutUndefined({
+		name,
+		baseUrl,
+		versions: entry.versions,
+		current: entry.current,
+		layout: entry.layout,
+		appendVersion: entry.appendVersion
+	}));
+	return Result.getOrThrowWith(decoded, (error) => /* @__PURE__ */ new Error(`defineConfig: ${error.message.replace(/\n\s*/g, " ")}`));
 };
-const resolveEntry = (name, entry, defaults, outputDir) => {
+const resolveEntry = (name, input, defaults, outputDir) => {
 	if (!SchemaVersioning.isSimpleName(name)) return fail(`schema "${name}" must be keyed by a simple file base name (no separators, no whitespace)`);
-	if (!Predicate.isObject(entry)) return fail(`schema "${name}" must be an object`);
-	if (!Schema.isSchema(entry.schema)) return fail(`schema "${name}" has a schema that is not an Effect Schema`);
-	if (entry.published !== void 0 && typeof entry.published !== "boolean") return fail(`schema "${name}" has a published that is not a boolean`);
-	const baseUrl = entry.baseUrl ?? defaults.baseUrl;
-	const hosting = resolveHosting(name, baseUrl, entry.layout);
-	const versioned = resolveVersions(name, entry);
-	if (baseUrl === "schemastore" && entry.catalog === void 0) return fail(`schema "${name}" must declare a catalog block under baseUrl "schemastore"`);
-	if (entry.catalog !== void 0 && (!Predicate.isObject(entry.catalog) || !Array.isArray(entry.catalog.fileMatch) || typeof entry.catalog.description !== "string")) return fail(`schema "${name}" declares an invalid catalog block (expected { description, fileMatch[] })`);
-	if (entry.catalog !== void 0 && entry.catalog.fileMatch.length === 0) return fail(`schema "${name}" declares a catalog with an empty fileMatch`);
-	const file = (version) => `${outputDir}/${SchemaVersioning.fileName(name, version, hosting.layout)}`;
-	const urlOf = (base) => (version) => SchemaVersioning.schemaUrl(base, name, version, hosting.layout);
-	const idOf = urlOf(hosting.idBase);
-	const catalogUrlOf = urlOf(hosting.catalogBase);
-	const current = versioned?.current;
+	const entry = decodeOrThrow(EntryInput, withoutUndefined(input), `schema "${name}" `);
+	const hosted = resolveIdentity(name, entry, defaults.baseUrl);
+	if (hosted.baseUrl === "schemastore" && entry.catalog === void 0) return fail(`schema "${name}" must declare a catalog block under baseUrl "schemastore"`);
+	const versions = hosted.resolvedVersions;
+	const current = hosted.resolvedCurrent;
+	const file = (version) => `${outputDir}/${hosted.fileNameFor(version)}`;
+	const generation = {
+		...entry.jsonSchema !== void 0 ? { jsonSchema: entry.jsonSchema } : {},
+		...entry.rootAnnotations !== void 0 ? { rootAnnotations: entry.rootAnnotations } : {}
+	};
 	const target = current === void 0 ? SchemaTarget.make({
 		schema: entry.schema,
-		$id: idOf(current),
+		$id: hosted.idFor(current),
 		name,
 		path: file(current),
 		published: entry.published ?? false,
-		...entry.jsonSchema !== void 0 ? { jsonSchema: entry.jsonSchema } : {},
-		...entry.rootAnnotations !== void 0 ? { rootAnnotations: entry.rootAnnotations } : {}
+		...generation
 	}) : SchemaTarget.make({
 		schema: entry.schema,
-		$id: idOf(current),
+		$id: hosted.idFor(current),
 		name,
 		path: file(current),
 		version: current,
 		published: entry.published ?? false,
-		...entry.jsonSchema !== void 0 ? { jsonSchema: entry.jsonSchema } : {},
-		...entry.rootAnnotations !== void 0 ? { rootAnnotations: entry.rootAnnotations } : {}
+		...generation
 	});
-	const frozen = versioned === void 0 ? [] : versioned.versions.filter((v) => v !== versioned.current).map((version) => ({
+	const frozen = versions.filter((v) => v !== current).map((version) => ({
 		version,
 		path: file(version),
-		url: catalogUrlOf(version)
+		$id: hosted.idFor(version),
+		url: hosted.urlFor(version)
 	}));
 	const catalog = entry.catalog === void 0 ? void 0 : CatalogEntry.assemble({
 		name,
 		description: entry.catalog.description,
 		fileMatch: entry.catalog.fileMatch,
-		baseUrl: hosting.catalogBase,
-		layout: hosting.layout,
-		...versioned !== void 0 ? {
-			versions: versioned.versions,
-			current: versioned.current
+		baseUrl: hosted.catalogBase,
+		layout: hosted.resolvedLayout,
+		appendVersion: hosted.resolvedAppendVersion,
+		...current !== void 0 ? {
+			versions,
+			current
 		} : {}
 	});
 	return {
 		name,
 		target,
 		frozen,
-		drift: resolveSchemaDrift(name, entry.drift, defaults.drift),
+		drift: entry.drift ?? defaults.drift,
 		...catalog !== void 0 ? { catalog } : {}
 	};
 };
@@ -180,44 +179,41 @@ const assertUniquePaths = (paths) => {
 * for the catalog URL, forcing the `"flat"` layout; any other `baseUrl` is
 * used as one base for both, defaulting to the `"versioned"` layout.
 *
-* Throws a plain `Error` (never a raw `TypeError`) naming the offending
-* schema on: a non-object `input`; an empty `schemas` record; a
-* missing/empty `outputDir`; a schema key that is not a simple file base
-* name; a schema whose `schema` is not an Effect Schema; a schema with no
-* `baseUrl` anywhere, or a `baseUrl` that is not a string; a `baseUrl` that
-* is neither `"schemastore"` nor an `https://` URL; a `versions` that is not
-* an array, or an empty `versions` array; a version label (or `current`)
-* that is not a string, or an otherwise invalid version label; two labels
-* spelling the same version; `current` given without `versions`, or naming
-* one not among them; a non-boolean `published`; `layout` declared under
-* `baseUrl: "schemastore"`; a missing `catalog` under
-* `baseUrl: "schemastore"`, or one with an empty `fileMatch`; an invalid
-* `drift` or top-level `onDrift`; and an output path (a target, a frozen
-* file, or the catalog path) declared twice, compared after a lexical
-* normalisation (`./`, `..`, trailing `/`) — the CLI's loader re-checks on
-* the resolved absolute paths. Branding the result lets a loader recognise a
-* config module's default export via {@link isSchemastoreConfig}.
+* Throws a plain `Error` (never a raw `TypeError`) on every malformed
+* input. The shape is decoded once per level with a `Schema.Struct`
+* (`errors: "all"`, so every issue on an entry is reported at once, and
+* `onExcessProperty: "error"`, so a typo'd key is named rather than
+* dropped); the message is `defineConfig: schema "<name>" ` followed by the
+* decode issues (`Expected string at ["baseUrl"]`). After a shape-clean
+* decode the cross-field rules run: the entry's identity — its
+* {@link HostedSchema}, or one built from `baseUrl`/`versions`/`current`/
+* `layout` and the config default — is validated by `HostedSchema` itself
+* (a `hosted` entry must be keyed by `hosted.name` and must not spell those
+* four fields beside it); a schema key must be a simple file base name; a
+* `catalog` is required under `baseUrl: "schemastore"`; an empty `schemas`
+* record is rejected; and an output path (a target, a frozen file, or the
+* catalog path) declared twice is rejected after a lexical normalisation
+* (`./`, `..`, trailing `/`) — the CLI's loader re-checks on the resolved
+* absolute paths. Branding the result lets a loader recognise a config
+* module's default export via {@link isSchemastoreConfig}.
 *
 * @public
 */
 const defineConfig = (input) => {
-	if (!Predicate.isObject(input)) return fail("expected a config object");
-	if (typeof input.outputDir !== "string" || input.outputDir.length === 0) return fail("outputDir is required");
-	const outputDir = trimSlashes(input.outputDir);
-	if (!Predicate.isObject(input.schemas) || Object.keys(input.schemas).length === 0) return fail("at least one schema is required");
-	if (input.onDrift !== void 0 && !ON_DRIFT.includes(input.onDrift)) return fail(`invalid onDrift "${String(input.onDrift)}"`);
-	if (input.catalogPath !== void 0 && (typeof input.catalogPath !== "string" || input.catalogPath.length === 0)) return fail("catalogPath must be a non-empty string when given");
+	const config = decodeOrThrow(ConfigInput, withoutUndefined(input), "");
+	const outputDir = trimSlashes(config.outputDir);
+	if (Object.keys(config.schemas).length === 0) return fail("at least one schema is required");
 	const defaults = {
-		baseUrl: input.baseUrl,
-		drift: resolveConfigDrift(input.drift)
+		baseUrl: config.baseUrl,
+		drift: config.drift ?? DriftPolicy.defaults.policy
 	};
-	const schemas = Object.entries(input.schemas).map(([name, entry]) => resolveEntry(name, entry, defaults, outputDir));
-	const catalogPath = input.catalogPath ?? `${outputDir}/catalog.json`;
+	const schemas = Object.entries(config.schemas).map(([name, entry]) => resolveEntry(name, entry, defaults, outputDir));
+	const catalogPath = config.catalogPath ?? `${outputDir}/catalog.json`;
 	assertUniquePaths([...schemas.flatMap((s) => [s.target.path, ...s.frozen.map((f) => f.path)]), catalogPath]);
 	return {
 		[ConfigBrand]: true,
 		outputDir,
-		onDrift: input.onDrift ?? DriftPolicy.defaults.onDrift,
+		onDrift: config.onDrift ?? DriftPolicy.defaults.onDrift,
 		catalogPath,
 		schemas
 	};
@@ -231,4 +227,4 @@ const defineConfig = (input) => {
 const isSchemastoreConfig = (value) => typeof value === "object" && value !== null && value[ConfigBrand] === true;
 
 //#endregion
-export { SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, defineConfig, isSchemastoreConfig };
+export { defineConfig, isSchemastoreConfig };

package/StoreDocument.js

@@ -207,6 +207,7 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 			const userIncludes = options.jsonSchema?.includeAnnotationKey;
 			const undeclared = /* @__PURE__ */ new Set();
 			const document = Schema.toJsonSchemaDocument(source, {
+				onExcessProperty: "error",
 				...options.jsonSchema,
 				includeAnnotationKey: (key) => {
 					if (KeywordFamilies.isDeclared(key)) return true;