@prosary/schema 0.0.0-stage → 0.0.1

package/.dist/index.d.mts

@@ -0,0 +1,123 @@
+import { MessageFormatElement } from "@formatjs/icu-messageformat-parser";
+/**
+ * The named formats every contract has without declaring them — FormatJS's
+ * defaults, less `currency`, which names no currency and so cannot format.
+ * A contract's own formats are declared in `prosary.config.ts`, and may
+ * redefine these.
+ */
+export declare const FORMATS: {
+  readonly number: readonly ["integer", "percent"];
+  readonly date: readonly ["short", "medium", "long", "full"];
+  readonly time: readonly ["short", "medium", "long", "full"];
+};
+/**
+ * One compiled message: the FormatJS AST `@prosary/kit` parsed an ICU message
+ * to, which the runtime formats without a parser.
+ */
+export type Ast = MessageFormatElement[];
+/** The kinds of value a named format applies to. */
+export type Kind = "number" | "date" | "time";
+/**
+ * Named formats, by kind: what a message refers to by name
+ * (`{amount, number, price}`) and a helper takes in place of options.
+ */
+export interface Formats {
+  readonly number?: Readonly<Record<string, Intl.NumberFormatOptions>>;
+  readonly date?: Readonly<Record<string, Intl.DateTimeFormatOptions>>;
+  readonly time?: Readonly<Record<string, Intl.DateTimeFormatOptions>>;
+}
+/**
+ * A contract as `@prosary/kit` builds it: the source locale, every locale a
+ * bundle exists for, and every message key. Plain data — no message text.
+ *
+ * `arguments` is a type carrier only: the kit declares it with the values
+ * each message takes and never emits it, so a definition infers a typed
+ * resolver without holding anything at runtime.
+ */
+export interface Definition {
+  /** The locale the source messages are written in. */
+  readonly locale: string;
+  /** Every locale a bundle is built for, the source locale first. */
+  readonly locales: readonly string[];
+  /** Every message key, in source order. */
+  readonly messages: readonly string[];
+  /** The named formats `prosary.config.ts` declares, by kind. */
+  readonly formats?: Formats;
+  /** Never present at runtime; carries each message's values in the types. */
+  readonly arguments?: object;
+}
+/** The locales of a contract. */
+export type Locale<D extends Definition> = D["locales"][number];
+/** The message keys of a contract: what each message goes by. */
+export type Key<D extends Definition> = D["messages"][number];
+/**
+ * The names a format of one kind goes by: the built-in ones, and the ones the
+ * contract declares.
+ */
+export type Named<D extends Definition, K extends Kind> = (typeof FORMATS)[K][number] | (D["formats"] extends Readonly<Record<K, infer F>> ? keyof F & string : never);
+/**
+ * The values one message takes: read off the contract's `arguments` carrier,
+ * or any record when the definition carries none.
+ */
+export type Values<D extends Definition, K extends Key<D>> = K extends keyof NonNullable<D["arguments"]> ? NonNullable<D["arguments"]>[K] : Record<string, unknown>;
+/**
+ * Messages of one locale, compiled: message key to AST. Partial by design —
+ * an app may hold the whole locale or only the part it has loaded.
+ */
+export type Bundle<D extends Definition> = { [K in Key<D>]?: Ast; };
+/** One reason a value is not what the contract asks for. */
+export interface Issue {
+  /** What is wrong. */
+  message: string;
+  /** Where in the value, when it is not the value itself. */
+  path?: string[];
+}
+/**
+ * The validation bundle for a contract: `check` answers as a type guard,
+ * `assert` throws a `SchemaError` carrying every issue.
+ */
+export interface Schema<D extends Definition> {
+  /** The contract the schema was derived from. */
+  definition: D;
+  check: {
+    locale: (value: unknown) => value is Locale<D>;
+    key: (value: unknown) => value is Key<D>;
+    bundle: (value: unknown) => value is Bundle<D>;
+    timeZone: (value: unknown) => value is string;
+    convention: (value: unknown) => value is string;
+  };
+  assert: {
+    locale: (value: unknown) => asserts value is Locale<D>;
+    key: (value: unknown) => asserts value is Key<D>;
+    bundle: (value: unknown) => asserts value is Bundle<D>;
+    timeZone: (value: unknown) => asserts value is string;
+    convention: (value: unknown) => asserts value is string;
+  };
+}
+/**
+ * Raised when an assertion rejects a value. Carries the concrete
+ * {@link Issue}s — each with its own message and path — rather than
+ * collapsing them into a single string, so callers can react to every failure
+ * individually.
+ */
+export declare class SchemaError extends Error {
+  readonly issues: Issue[];
+  constructor(issues: Issue[]);
+}
+/**
+ * Derives the validation bundle for a contract — what proves a locale, a
+ * message key, or a bundle that arrives at runtime (fetched, imported,
+ * restored from storage) before the service adopts it.
+ *
+ * A bundle may hold any part of the contract's messages, but nothing outside
+ * it: every key must be a message the contract declares, mapped to a compiled
+ * message.
+ *
+ * A time zone and a convention — the locale values are formatted by — are
+ * proven against the runtime rather than the contract: any IANA zone, any
+ * well-formed locale tag.
+ *
+ * @param definition - The contract `@prosary/kit` built.
+ * @returns The {@link Schema} for the contract.
+ */
+export declare const defineSchema: <D extends Definition>(definition: D) => Schema<D>;

package/.dist/index.mjs

@@ -0,0 +1,96 @@
+import { record } from "objectively";
+const FORMATS = {
+	number: ["integer", "percent"],
+	date: [
+		"short",
+		"medium",
+		"long",
+		"full"
+	],
+	time: [
+		"short",
+		"medium",
+		"long",
+		"full"
+	]
+};
+const summarize = (issues) => issues.map((issue) => issue.path?.length ? `${issue.path.join(".")}: ${issue.message}` : issue.message).join("\n");
+var SchemaError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(summarize(issues));
+		this.name = "SchemaError";
+		this.issues = issues;
+	}
+};
+const isAst = (value) => {
+	return Array.isArray(value) && value.every((element) => record(element) && typeof element.type === "number");
+};
+const defineSchema = (definition) => {
+	const locales = new Set(definition.locales);
+	const messages = new Set(definition.messages);
+	const inspect = {
+		locale: (value) => {
+			if (locales.has(value)) return [];
+			return [{ message: `${JSON.stringify(value)} is not a locale of the contract` }];
+		},
+		key: (value) => {
+			if (messages.has(value)) return [];
+			return [{ message: `${JSON.stringify(value)} is not a message of the contract` }];
+		},
+		bundle: (value) => {
+			if (!record(value)) return [{ message: "a bundle must be a record of compiled messages" }];
+			const issues = [];
+			for (const [key, ast] of Object.entries(value)) if (!messages.has(key)) issues.push({
+				message: "is not a message of the contract",
+				path: [key]
+			});
+			else if (!isAst(ast)) issues.push({
+				message: "is not a compiled message",
+				path: [key]
+			});
+			return issues;
+		}
+	};
+	const settings = {
+		timeZone: (value) => {
+			try {
+				if (typeof value === "string") {
+					new Intl.DateTimeFormat(void 0, { timeZone: value });
+					return [];
+				}
+			} catch {}
+			return [{ message: `${JSON.stringify(value)} is not an IANA time zone` }];
+		},
+		convention: (value) => {
+			try {
+				if (typeof value === "string" && value !== "") {
+					Intl.getCanonicalLocales(value);
+					return [];
+				}
+			} catch {}
+			return [{ message: `${JSON.stringify(value)} is not a BCP 47 locale tag` }];
+		}
+	};
+	const assert = (issues) => {
+		if (issues.length > 0) throw new SchemaError(issues);
+	};
+	return {
+		definition,
+		check: {
+			locale: (value) => inspect.locale(value).length === 0,
+			key: (value) => inspect.key(value).length === 0,
+			bundle: (value) => inspect.bundle(value).length === 0,
+			timeZone: (value) => settings.timeZone(value).length === 0,
+			convention: (value) => settings.convention(value).length === 0
+		},
+		assert: {
+			locale: (value) => assert(inspect.locale(value)),
+			key: (value) => assert(inspect.key(value)),
+			bundle: (value) => assert(inspect.bundle(value)),
+			timeZone: (value) => assert(settings.timeZone(value)),
+			convention: (value) => assert(settings.convention(value))
+		}
+	};
+};
+export { FORMATS, SchemaError, defineSchema };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Thorwaldson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @prosary/schema
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Message contract types and runtime validation.

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@prosary/schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Message contract types and runtime validation",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobzio/prosary.git",
+    "directory": "packages/schema"
+  },
+  "type": "module",
+  "main": "./.dist/index.mjs",
+  "types": "./.dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.mts",
+      "import": "./.dist/index.mjs"
+    }
+  },
+  "files": [
+    ".dist"
+  ],
+  "dependencies": {
+    "@formatjs/icu-messageformat-parser": "^3.5.20",
+    "objectively": "^0.3.0"
+  },
+  "scripts": {
+    "build": "obuild",
+    "stub": "obuild --stub",
+    "lint": "oxlint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }