@effected/schemastore 0.10.0 → 0.12.0

package/SchemaVersioning.js

@@ -73,7 +73,7 @@ const bumpNext = (current, parsed, components) => {
 	}
 };
 const assertSimpleName = (name) => {
-	if (name.length === 0 || /[/\\\s]/.test(name)) throw new Error(`Schema name must be a non-empty simple file base name, got "${name}"`);
+	if (!SchemaVersioning.isSimpleName(name)) throw new Error(`Schema name must be a non-empty simple file base name, got "${name}"`);
 };
 const joinUrl = (baseUrl, file) => {
 	let end = baseUrl.length;
@@ -182,22 +182,39 @@ var SchemaVersioning = class SchemaVersioning {
 		return reparsed.success;
 	}
 	/**
+	* Whether a name is a simple file base name — non-empty, no path
+	* separators, no whitespace — the rule every schema name is held to
+	* ({@link SchemaVersioning.fileName} throws on anything else; `defineConfig`
+	* rejects a schema key the same way). One predicate so the two cannot drift.
+	*/
+	static isSimpleName(name) {
+		return name.length > 0 && !/[/\\\s]/.test(name);
+	}
+	/**
 	* Derives the schema file name for a catalog name: `name.json`
-	* unversioned, `name-<version>.json` versioned.
+	* 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.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) {
+	static fileName(name, version, layout = "flat", appendVersion = true) {
 		assertSimpleName(name);
-		return version === void 0 ? `${name}.json` : `${name}-${version}.json`;
+		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 = 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) {
-		return joinUrl(baseUrl, SchemaVersioning.fileName(name, version));
+	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.
@@ -205,9 +222,20 @@ var SchemaVersioning = class SchemaVersioning {
 	* Omitting `versions` selects the unversioned mode (`url` only,
 	* pointing at the plain `name.json`). Providing them selects the
 	* versioned mode: the `versions` map carries every label, and `url`
-	* points at the latest version's file. An **empty** `versions` array is
+	* points at `current` (default: the newest label under
+	* {@link SchemaVersioning.Order}). An **empty** `versions` array is
 	* a contradiction (versioned mode with no versions) and throws — pass
-	* `undefined` for the unversioned mode.
+	* `undefined` for the unversioned mode. `current`, when given, must
+	* compare equal under {@link SchemaVersioning.Order} to a member of
+	* `versions` or this throws; `url` is built from that member's own
+	* spelling (the `versions` map's key), not from the `current` argument
+	* 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"`) 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
@@ -215,14 +243,19 @@ var SchemaVersioning = class SchemaVersioning {
 	*/
 	static catalogUrls(options) {
 		const { baseUrl, name, versions } = options;
-		if (versions === void 0) return { url: SchemaVersioning.schemaUrl(baseUrl, name) };
+		const layout = options.layout ?? "flat";
+		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);
+		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, newest),
+			url: SchemaVersioning.schemaUrl(baseUrl, name, current, layout, appendVersion),
 			versions: map
 		};
 	}

package/SchemastoreConfig.js

@@ -1,42 +1,146 @@
 import { SchemaVersioning } from "./SchemaVersioning.js";
 import { CatalogEntry } from "./CatalogEntry.js";
 import { DriftPolicy } from "./DriftPolicy.js";
-import { Schema } from "effect";
+import { HostedSchema } from "./HostedSchema.js";
+import { SchemaTarget } from "./SchemaTarget.js";
+import { Predicate, Result, Schema } from "effect";
 
 //#region src/SchemastoreConfig.ts
 const ConfigBrand = Symbol.for("@effected/schemastore/SchemastoreConfig");
-const DriftSchema = Schema.Struct({
-	policy: Schema.optionalKey(Schema.Literals([
-		"strict",
-		"semantic",
-		"allow"
-	])),
-	onDrift: Schema.optionalKey(Schema.Literals(["error", "warn"]))
-});
-const CatalogConfigSchema = Schema.Struct({
-	name: Schema.String.check(Schema.isMinLength(1)),
+const fail = (message) => {
+	throw new Error(`defineConfig: ${message}`);
+};
+const trimSlashes = (dir) => {
+	let end = dir.length;
+	while (end > 1 && dir.charCodeAt(end - 1) === 47) end -= 1;
+	return dir.slice(0, end);
+};
+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.Array(Schema.String),
-	baseUrl: Schema.String.check(Schema.isMinLength(1)),
-	path: Schema.String.check(Schema.isMinLength(1))
+	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 decodeOrThrow = (schema, value, what) => {
-	const result = Schema.decodeUnknownResult(schema)(value);
-	if (result._tag === "Failure") throw new Error(`defineConfig: invalid ${what}: ${String(result.failure)}`);
-	return result.success;
+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 versionsByName = (schemas) => {
-	const map = /* @__PURE__ */ new Map();
-	for (const target of schemas) {
-		if (target.name === void 0 || target.version === void 0) continue;
-		const version = target.version;
-		const versions = map.get(target.name) ?? [];
-		const duplicate = versions.find((v) => SchemaVersioning.Order(v, version) === 0);
-		if (duplicate !== void 0) throw new Error(`defineConfig: schema "${target.name}" declares the same version twice, as "${duplicate}" and "${version}"`);
-		versions.push(version);
-		map.set(target.name, versions);
+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;
 	}
-	return map;
+	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, input, defaults, outputDir) => {
+	if (!SchemaVersioning.isSimpleName(name)) return fail(`schema "${name}" must be keyed by a simple file base name (no separators, no whitespace)`);
+	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: hosted.idFor(current),
+		name,
+		path: file(current),
+		published: entry.published ?? false,
+		...generation
+	}) : SchemaTarget.make({
+		schema: entry.schema,
+		$id: hosted.idFor(current),
+		name,
+		path: file(current),
+		version: current,
+		published: entry.published ?? false,
+		...generation
+	});
+	const frozen = versions.filter((v) => v !== current).map((version) => ({
+		version,
+		path: file(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: hosted.catalogBase,
+		layout: hosted.resolvedLayout,
+		appendVersion: hosted.resolvedAppendVersion,
+		...current !== void 0 ? {
+			versions,
+			current
+		} : {}
+	});
+	return {
+		name,
+		target,
+		frozen,
+		drift: entry.drift ?? defaults.drift,
+		...catalog !== void 0 ? { catalog } : {}
+	};
 };
 const normalizePath = (raw) => {
 	const absolute = raw.startsWith("/");
@@ -52,11 +156,11 @@ const normalizePath = (raw) => {
 	}
 	return `${absolute ? "/" : ""}${out.join("/")}`;
 };
-const assertUniquePaths = (schemas, catalog) => {
+const assertUniquePaths = (paths) => {
 	const seen = /* @__PURE__ */ new Set();
-	for (const p of [...schemas.map((target) => target.path), ...catalog.map((entry) => entry.path)]) {
+	for (const p of paths) {
 		const normalized = normalizePath(p);
-		if (seen.has(normalized)) throw new Error(`defineConfig: output path "${p}" is declared twice`);
+		if (seen.has(normalized)) fail(`output path "${p}" is declared twice`);
 		seen.add(normalized);
 	}
 };
@@ -64,49 +168,54 @@ const assertUniquePaths = (schemas, catalog) => {
 * Validate and assemble a `schemastore.config.ts` value.
 *
 * @remarks
-* Pure: no IO, no Effect. Identity-with-validation over the input, filling
-* drift defaults, deriving each catalog entry's `versions` from EVERY
-* versioned schema of that name (published or not — the entry is what gets
-* submitted to become published), and branding the result so a loader can
-* recognise a config module's default export. Throws a plain `Error` on a
-* bad input; the CLI wraps it into its typed config-load error. Rejects an
-* output `path` declared twice across schemas and catalog entries, compared
-* after a lexical normalisation (`./`, `..`, trailing `/`); the CLI's loader
-* re-checks on the resolved absolute paths.
+* Pure: no IO, no Effect. `$id`, the write `path` and every catalog URL are
+* derived from ONE layout (`outputDir`, `baseUrl` and `layout`) so they
+* cannot disagree with each other. `versions` names every label a schema
+* advertises; `current` (default: the newest under
+* {@link SchemaVersioning.Order}) is the one generated at `target`, and every
+* other label becomes a {@link FrozenVersion} the CLI verifies but does not
+* regenerate. `baseUrl: "schemastore"` expands to
+* {@link SCHEMASTORE_ID_BASE} for `$id` and {@link SCHEMASTORE_CATALOG_BASE}
+* 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`) 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 (!Array.isArray(input.schemas) || input.schemas.length === 0) throw new Error("defineConfig: at least one schema is required");
-	const drift = decodeOrThrow(DriftSchema, input.drift ?? {}, "drift block");
-	const versions = versionsByName(input.schemas);
-	const rawCatalog = input.catalog ?? [];
-	if (!Array.isArray(rawCatalog)) throw new Error("defineConfig: invalid catalog: expected an array of catalog entries");
-	const catalog = rawCatalog.map((raw) => {
-		const label = typeof raw === "object" && raw !== null ? String(raw.name) : String(raw);
-		const config = decodeOrThrow(CatalogConfigSchema, raw, `catalog entry "${label}"`);
-		const found = versions.get(config.name);
-		if (found === void 0) throw new Error(`defineConfig: catalog entry "${config.name}" matches no versioned schema`);
-		return {
-			config,
-			entry: CatalogEntry.assemble({
-				name: config.name,
-				description: config.description,
-				fileMatch: config.fileMatch,
-				baseUrl: config.baseUrl,
-				versions: found
-			})
-		};
-	});
-	assertUniquePaths(input.schemas, catalog.map((c) => c.config));
+	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: config.baseUrl,
+		drift: config.drift ?? DriftPolicy.defaults.policy
+	};
+	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,
-		schemas: input.schemas,
-		catalog,
-		drift: {
-			policy: drift.policy ?? DriftPolicy.defaults.policy,
-			onDrift: drift.onDrift ?? DriftPolicy.defaults.onDrift
-		}
+		outputDir,
+		onDrift: config.onDrift ?? DriftPolicy.defaults.onDrift,
+		catalogPath,
+		schemas
 	};
 };
 /**

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;