@effected/schemastore 0.11.0 → 0.13.0

package/CatalogEntry.js

@@ -99,8 +99,9 @@ var CatalogEntry = class CatalogEntry extends Schema.Class("CatalogEntry")({
 	* {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
 	* versioned mode (the `versions` map and latest-pointing `url` are
 	* derived), omit it for the unversioned mode. `layout` (default
-	* `"flat"`) and `current` (default: the newest label) are forwarded to
-	* {@link SchemaVersioning.catalogUrls} verbatim. Throws an `Error` naming
+	* `"flat"`), `appendVersion` (default `true`) and `current` (default: the
+	* newest label) are forwarded to {@link SchemaVersioning.catalogUrls}
+	* verbatim. Throws an `Error` naming
 	* both spellings when two labels compare equal under
 	* {@link SchemaVersioning.Order} (`1.2` and `1.2.0`): each would be its
 	* own key and URL for one document.
@@ -112,6 +113,7 @@ var CatalogEntry = class CatalogEntry extends Schema.Class("CatalogEntry")({
 			name: options.fileBaseName ?? options.name,
 			...options.versions !== void 0 ? { versions: options.versions } : {},
 			...options.layout !== void 0 ? { layout: options.layout } : {},
+			...options.appendVersion !== void 0 ? { appendVersion: options.appendVersion } : {},
 			...options.current !== void 0 ? { current: options.current } : {}
 		});
 		return CatalogEntry.make({

package/HostedSchema.js

@@ -0,0 +1,230 @@
+import { SchemaVersioning } from "./SchemaVersioning.js";
+import { Option, Result, Schema } from "effect";
+
+//#region src/HostedSchema.ts
+/** 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 RAW_GITHUB_BASE = "https://raw.githubusercontent.com";
+const trimSlashes = (url) => {
+	let end = url.length;
+	while (end > 0 && url.charCodeAt(end - 1) === 47) end -= 1;
+	return url.slice(0, end);
+};
+const describeDirectoryUrl = (raw) => {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		return "expected \"schemastore\" or an https:// URL";
+	}
+	if (url.protocol !== "https:" || url.host.length === 0) return "expected \"schemastore\" or an https:// URL";
+	if (url.search.length > 0 || raw.endsWith("?")) return "a base URL cannot carry a query";
+	if (url.hash.length > 0 || raw.endsWith("#")) return "a base URL cannot carry a fragment";
+	if (url.username.length > 0 || url.password.length > 0) return "a base URL cannot carry credentials";
+};
+const isOwnerRepo = (repo) => /^[^/\s]+\/[^/\s]+$/.test(repo);
+const resolve = (fields) => {
+	if (!SchemaVersioning.isSimpleName(fields.name)) return Result.fail(`must be keyed by a simple file base name (no separators, no whitespace)`);
+	const appendVersion = fields.appendVersion ?? true;
+	let hosting;
+	if (fields.baseUrl === "schemastore") {
+		if (fields.layout !== void 0) return Result.fail(`declares layout "${fields.layout}" under baseUrl "schemastore", which serves only the flat layout`);
+		hosting = {
+			idBase: SCHEMASTORE_ID_BASE,
+			catalogBase: SCHEMASTORE_CATALOG_BASE,
+			layout: "flat",
+			appendVersion
+		};
+	} else {
+		const problem = describeDirectoryUrl(fields.baseUrl);
+		if (problem !== void 0) return Result.fail(`has baseUrl "${fields.baseUrl}"; ${problem}`);
+		hosting = {
+			idBase: fields.baseUrl,
+			catalogBase: fields.baseUrl,
+			layout: fields.layout ?? "versioned",
+			appendVersion
+		};
+	}
+	if (!appendVersion && hosting.layout !== "versioned") return Result.fail(`declares appendVersion: false under the "${hosting.layout}" layout, where every version would share one file name; only the "versioned" layout can drop the suffix`);
+	if (fields.versions === void 0) {
+		if (fields.current !== void 0) return Result.fail(`declares current "${fields.current}" without versions`);
+		return Result.succeed({
+			hosting,
+			versions: {
+				versions: [],
+				current: void 0
+			}
+		});
+	}
+	if (fields.versions.length === 0) return Result.fail(`declares versions as an empty array; omit versions for an unversioned schema`);
+	const versions = [];
+	for (const label of fields.versions) {
+		const parsed = SchemaVersioning.parseResult(label);
+		if (Result.isFailure(parsed)) return Result.fail(`has an invalid version label "${label}": ${parsed.failure.message}`);
+		const duplicate = versions.find((v) => SchemaVersioning.Order(v, parsed.success) === 0);
+		if (duplicate !== void 0) return Result.fail(`declares the same version twice, as "${duplicate}" and "${parsed.success}"`);
+		versions.push(parsed.success);
+	}
+	if (fields.current === void 0) return Result.succeed({
+		hosting,
+		versions: {
+			versions,
+			current: Option.getOrThrow(SchemaVersioning.latest(versions))
+		}
+	});
+	const current = SchemaVersioning.parseResult(fields.current);
+	if (Result.isFailure(current)) return Result.fail(`has an invalid version label "${fields.current}": ${current.failure.message}`);
+	const match = versions.find((v) => SchemaVersioning.Order(v, current.success) === 0);
+	if (match === void 0) return Result.fail(`declares current "${fields.current}" which is not one of its versions`);
+	return Result.succeed({
+		hosting,
+		versions: {
+			versions,
+			current: match
+		}
+	});
+};
+const HostedSchemaFields = Schema.Struct({
+	name: Schema.String,
+	baseUrl: Schema.String,
+	versions: Schema.optionalKey(Schema.Array(Schema.String)),
+	current: Schema.optionalKey(Schema.String),
+	layout: Schema.optionalKey(Schema.Literals(["flat", "versioned"])),
+	appendVersion: Schema.optionalKey(Schema.Boolean)
+}).check(Schema.makeFilter((fields) => {
+	const resolved = resolve(fields);
+	return Result.isFailure(resolved) ? `schema "${fields.name}" ${resolved.failure}` : void 0;
+}));
+/**
+* Where a JSON Schema document is hosted and which version of it is current
+* — the one value an application derives its `$schema` URL from and hands
+* to `defineConfig`, so the URL the code emits and the `$id` the CLI writes
+* cannot disagree.
+*
+* @remarks
+* Build one with {@link HostedSchema.github},
+* {@link HostedSchema.schemastore} or
+* {@link HostedSchema.custom}; each validates the identity and
+* throws a plain `Error` naming the reason. The derivation is
+* {@link SchemaVersioning.schemaUrl}'s: `<base>/<name>.json` unversioned,
+* `<base>/<name>-<version>.json` under the `"flat"` layout and
+* `<base>/<version>/<name>-<version>.json` under `"versioned"` (or
+* `<base>/<version>/<name>.json` with `appendVersion: false`, when the
+* version directory alone should name the file). The raw fields are what
+* `defineConfig` accepts by hand (`baseUrl`, `versions`, `current`,
+* `layout`, `appendVersion`); the getters are the resolved identity.
+*
+* @example
+* ```ts
+* import { HostedSchema } from "@effected/schemastore";
+* import { Schema } from "effect";
+*
+* export const OutputSchema = HostedSchema.github({
+*   repo: "savvy-web/silk-release-action",
+*   path: "schemas",
+*   name: "silk-release-action.output",
+*   versions: ["5.2"],
+* });
+*
+* // In the application: every payload names the schema it was written against.
+* const Output = Schema.Struct({ $schema: Schema.Literal(OutputSchema.$id) });
+*
+* // In schemastore.config.ts: the same value, so nothing is re-derived.
+* // schemas: { [OutputSchema.name]: { schema: Output, hosted: OutputSchema } }
+* ```
+*
+* @public
+*/
+var HostedSchema = class extends Schema.Class("HostedSchema")(HostedSchemaFields) {
+	/** A schema served raw from a GitHub repository. */
+	static github(input) {
+		const { repo, branch, path, ...rest } = input;
+		if (!isOwnerRepo(repo)) throw new Error(`schema "${input.name}" has repo "${repo}"; expected owner/repo`);
+		const segments = [
+			RAW_GITHUB_BASE,
+			repo,
+			branch ?? "main",
+			...path === void 0 ? [] : [path]
+		];
+		return construct({
+			...rest,
+			baseUrl: trimSlashes(segments.join("/"))
+		});
+	}
+	/** A schema published to SchemaStore: `$id` on {@link SCHEMASTORE_ID_BASE}, catalog URL on {@link SCHEMASTORE_CATALOG_BASE}, flat layout. */
+	static schemastore(input) {
+		return construct({
+			...input,
+			baseUrl: "schemastore"
+		});
+	}
+	/** A schema served from any `https://` directory. */
+	static custom(input) {
+		const { baseUrl, ...rest } = input;
+		return construct({
+			...rest,
+			baseUrl: trimSlashes(typeof baseUrl === "string" ? baseUrl : baseUrl.href)
+		});
+	}
+	get resolved() {
+		return Result.getOrThrow(resolve(this));
+	}
+	/** The base `$id` is derived from: {@link SCHEMASTORE_ID_BASE} under SchemaStore, else `baseUrl`. */
+	get idBase() {
+		return this.resolved.hosting.idBase;
+	}
+	/** The base the catalog URL is derived from: {@link SCHEMASTORE_CATALOG_BASE} under SchemaStore, else `baseUrl`. */
+	get catalogBase() {
+		return this.resolved.hosting.catalogBase;
+	}
+	/** The effective layout: `"flat"` under SchemaStore, else `layout` defaulting to `"versioned"`. */
+	get resolvedLayout() {
+		return this.resolved.hosting.layout;
+	}
+	/** Whether versioned file names carry the `-<version>` suffix: `appendVersion` defaulting to `true`. */
+	get resolvedAppendVersion() {
+		return this.resolved.hosting.appendVersion;
+	}
+	/** Every advertised version, parsed; empty for an unversioned schema. */
+	get resolvedVersions() {
+		return this.resolved.versions.versions;
+	}
+	/** The current version — `current`, else the newest of `versions`; `undefined` for an unversioned schema. */
+	get resolvedCurrent() {
+		return this.resolved.versions.current;
+	}
+	/** The `$id` of the current document — what an application writes as `$schema`. */
+	get $id() {
+		return this.idFor(this.resolvedCurrent);
+	}
+	/** The catalog URL of the current document; equals {@link HostedSchema.$id} except under SchemaStore. */
+	get url() {
+		return this.urlFor(this.resolvedCurrent);
+	}
+	/** The current document's file name relative to the output directory. */
+	get fileName() {
+		return this.fileNameFor(this.resolvedCurrent);
+	}
+	/** The `$id` of the document at `version` (or the unversioned document). */
+	idFor(version) {
+		return SchemaVersioning.schemaUrl(this.idBase, this.name, this.parseLabel(version), this.resolvedLayout, this.resolvedAppendVersion);
+	}
+	/** The catalog URL of the document at `version` (or the unversioned document). */
+	urlFor(version) {
+		return SchemaVersioning.schemaUrl(this.catalogBase, this.name, this.parseLabel(version), this.resolvedLayout, this.resolvedAppendVersion);
+	}
+	/** The file name of the document at `version` (or the unversioned document), relative to the output directory. */
+	fileNameFor(version) {
+		return SchemaVersioning.fileName(this.name, this.parseLabel(version), this.resolvedLayout, this.resolvedAppendVersion);
+	}
+	parseLabel(version) {
+		if (version === void 0) return;
+		return Result.getOrThrowWith(SchemaVersioning.parseResult(version), (error) => /* @__PURE__ */ new Error(`HostedSchema "${this.name}": invalid version label "${version}": ${error.message}`));
+	}
+};
+const construct = (fields) => Result.getOrThrowWith(Schema.decodeUnknownResult(HostedSchema)(fields), (error) => new Error(error.message));
+
+//#endregion
+export { HostedSchema, SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE };