@maroonedog/luq 2.2.0 → 2.3.0

package/dist/standard-schema/to-standard-schema.mjs

@@ -1,19 +1,18 @@
 import { splitIssuePath } from "./split-issue-path.mjs";
-/** package.json の name と揃える。消費側がエラー表示に使う。 */
+/** Matches the package name. Consumers show it in error output. */
 const VENDOR = "luq";
 const COLLECT_EVERY_ISSUE = {
     abortEarly: false,
     abortEarlyOnEachField: false,
 };
 /**
- * 元の Validator のメンバー (validate / parse / pick / pickAll) はそのまま残る。
- * 返り値は Validator でもあるので、片方のためにもう片方を諦める必要は無い。
+ * The original validator's members stay. What comes back is still a
+ * Validator, so neither face has to be given up for the other.
  */
 export function toStandardSchema(validator) {
-    // アサーションを書かずに組み立てる。src/core/type-erasure.ts が
-    // 「型を破ってよい唯一の場所」で、ここはその場所ではない。
-    // 各メンバーを明示的に写すので、Validator に新しいメンバーが増えたときは
-    // ここがコンパイルエラーになる — 黙って落ちるより良い。
+    // Assembled without a type assertion; this is not a file allowed to write
+    // one. Copying each member by name means a new member on Validator breaks
+    // the build here, which beats being dropped in silence.
     const props = {
         version: 1,
         vendor: VENDOR,
@@ -33,25 +32,19 @@ export function toStandardSchema(validator) {
     };
 }
 /**
- * code と severity は仕様に置き場所が無いので落ちる。message は Luq が
- * 組み立て済みのものをそのまま渡す。
+ * code and severity have nowhere to go in the spec, so they are dropped. The
+ * message is passed through as already composed.
  */
 function toStandardIssue(issue) {
     return { message: issue.message, path: splitIssuePath(issue.path) };
 }
 // ---------------------------------------------------------------------------
-// なぜコアの build() が ~standard を常に生やさないのか（実測に基づく判断）
+// Why build() does not simply put ~standard on every validator.
 //
-//   core-only                      gzip  7,420 B
-//   core + standard-schema         gzip  7,732 B   (+312 B)
-//   six-plugin                     gzip  8,373 B
-//   six-plugin + standard-schema   gzip  8,692 B   (+319 B)
-//
-// コアに同梱すると、Standard Schema を使わない利用者も 312 B を払う。中核が
-// 7,420 B なので 4.2% にあたり、「使った分しか入らない」という約束と噛み合わない。
-// サブパスにしておけば import しない限り 0 B で、tRPC などに渡したい人だけが払う。
-//
-// 代償は、利用者が toStandardSchema() で1回包む必要があること。build() が
-// 直接 ~standard を持つほうが体験は良いが、その体験のために全員に課金する形に
-// なるので取らなかった。将来コアに入れるなら、この 312 B が判断材料になる。
+// It would be the nicer experience — no wrapping call — but it bills everyone
+// for it, including the majority who never hand a validator to a spec
+// consumer. Measured against the core bundle the surcharge was a few percent,
+// which does not fit "you only ship what you used". As a subpath it costs
+// nothing until imported. Re-measure before revisiting the decision; the
+// figures live with the size budget, not here.
 // ---------------------------------------------------------------------------

package/dist/standard-schema/unrepresentable-rule-error.d.ts

@@ -0,0 +1,15 @@
+export declare class UnrepresentableRuleError extends Error {
+    readonly fieldPath: string;
+    readonly pluginName: string;
+    readonly reason: string;
+    constructor(fieldPath: string, pluginName: string, reason: string);
+}
+/** What to do with an unwritable declaration. Defaults to "throw". */
+export type UnrepresentablePolicy = "throw" | "omit";
+/**
+ * Reads the policy out of `libraryOptions`.
+ *
+ * An unrecognised value falls to throw. A misspelled `omit` landing on the
+ * strict side is correct; landing on the lax side is an incident.
+ */
+export declare function readUnrepresentablePolicy(libraryOptions: Record<string, unknown> | undefined): UnrepresentablePolicy;

package/dist/standard-schema/unrepresentable-rule-error.js

@@ -0,0 +1,43 @@
+"use strict";
+// ===========================================================================
+// L10 src/standard-schema/unrepresentable-rule-error.ts
+//
+// Meeting a declaration that cannot be written as JSON Schema throws, by
+// default.
+//
+// Dropping it silently is not on offer. What comes out of here gets USED FOR
+// VALIDATION by whoever receives it, so dropping a `.custom()` produces a
+// schema that admits values it must not — with no trace of the omission. The
+// missing constraint is discovered by the incident it causes.
+//
+// Anyone for whom dropping is fine — emitting for documentation or for a form
+// layout rather than for validation — can ask for it explicitly through
+// libraryOptions, which the spec provides for exactly this kind of agreement.
+// The point is that the lax choice is never the default, and that having made
+// it stays visible in the caller's code.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnrepresentableRuleError = void 0;
+exports.readUnrepresentablePolicy = readUnrepresentablePolicy;
+class UnrepresentableRuleError extends Error {
+    constructor(fieldPath, pluginName, reason) {
+        super(`"${fieldPath}" declares ${pluginName}, which Luq cannot express in ` +
+            `JSON Schema: ${reason}. Pass ` +
+            `libraryOptions: { unrepresentable: "omit" } to drop it instead — ` +
+            `the emitted schema then accepts values this validator rejects.`);
+        this.fieldPath = fieldPath;
+        this.pluginName = pluginName;
+        this.reason = reason;
+        this.name = "UnrepresentableRuleError";
+    }
+}
+exports.UnrepresentableRuleError = UnrepresentableRuleError;
+/**
+ * Reads the policy out of `libraryOptions`.
+ *
+ * An unrecognised value falls to throw. A misspelled `omit` landing on the
+ * strict side is correct; landing on the lax side is an incident.
+ */
+function readUnrepresentablePolicy(libraryOptions) {
+    return libraryOptions?.["unrepresentable"] === "omit" ? "omit" : "throw";
+}

package/dist/standard-schema/unrepresentable-rule-error.mjs

@@ -0,0 +1,38 @@
+// ===========================================================================
+// L10 src/standard-schema/unrepresentable-rule-error.ts
+//
+// Meeting a declaration that cannot be written as JSON Schema throws, by
+// default.
+//
+// Dropping it silently is not on offer. What comes out of here gets USED FOR
+// VALIDATION by whoever receives it, so dropping a `.custom()` produces a
+// schema that admits values it must not — with no trace of the omission. The
+// missing constraint is discovered by the incident it causes.
+//
+// Anyone for whom dropping is fine — emitting for documentation or for a form
+// layout rather than for validation — can ask for it explicitly through
+// libraryOptions, which the spec provides for exactly this kind of agreement.
+// The point is that the lax choice is never the default, and that having made
+// it stays visible in the caller's code.
+// ===========================================================================
+export class UnrepresentableRuleError extends Error {
+    constructor(fieldPath, pluginName, reason) {
+        super(`"${fieldPath}" declares ${pluginName}, which Luq cannot express in ` +
+            `JSON Schema: ${reason}. Pass ` +
+            `libraryOptions: { unrepresentable: "omit" } to drop it instead — ` +
+            `the emitted schema then accepts values this validator rejects.`);
+        this.fieldPath = fieldPath;
+        this.pluginName = pluginName;
+        this.reason = reason;
+        this.name = "UnrepresentableRuleError";
+    }
+}
+/**
+ * Reads the policy out of `libraryOptions`.
+ *
+ * An unrecognised value falls to throw. A misspelled `omit` landing on the
+ * strict side is correct; landing on the lax side is an incident.
+ */
+export function readUnrepresentablePolicy(libraryOptions) {
+    return libraryOptions?.["unrepresentable"] === "omit" ? "omit" : "throw";
+}

package/dist/types/index.d.ts

@@ -44,12 +44,12 @@ export type CheckOutcome = {
 export declare const PASS: CheckOutcome;
 export declare function fail(detail: IssueDetail): CheckOutcome;
 /**
- * クロスフィールドの判定が返せるもの。真偽だけでも、メッセージ付きでもよい。
+ * What a cross-field check may answer: a boolean, or a boolean with a message.
  *
- * ここ (L0) にあるのは、チェーン層が `stitch` の呼び出し側の型を組むときに
- * 参照するからである。プラグイン (L7) に置いたままだと L3 -> L7 の import に
- * なり、層が逆流する。プラグイン側の `StitchOutcome` はこれの別名で、
- * 公開名は変えていない。
+ * It lives at the bottom layer because the chain layer needs it to build the
+ * caller-facing type of `stitch`. Left in the plugin, that would be an import
+ * running outward from the chain, which no layer may do. The plugin's
+ * `StitchOutcome` is an alias of this one, so the public name is unchanged.
  */
 export interface CrossFieldOutcome {
     readonly valid: boolean;
@@ -79,14 +79,14 @@ export declare function isArray(value: unknown): value is readonly unknown[];
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 export declare function isStringArray(value: unknown): value is readonly string[];
 /**
- * 文字列の長さをコードポイントで数える。
+ * Counts a string's length in code points.
  *
- * `.length` は UTF-16 のコード単位を数えるので、絵文字や星域文字が 2 と数えられる。
- * JSON Schema §6.3.1 は minLength / maxLength をコードポイントで数えると定めており、
- * 利用者が「3文字」と書くときに期待するのもコードポイントのほう。
+ * `.length` counts UTF-16 code units, so an emoji or any astral character
+ * counts as two. JSON Schema §6.3.1 defines minLength / maxLength in code
+ * points, and code points are also what someone writing "three characters"
+ * means.
  *
- * 1.x は `.length` を使っていた (docs/legacy-spec/plugin-catalog-core.md が
- * 「暗黙の挙動で、まわりに落ちるテストがある。明示的な決定にすべき」と記録している)。
- * ここでその決定をした。星域文字を含む文字列では 1.x と判定が変わる。
+ * This is a deliberate decision, not an inherited one: strings containing
+ * astral characters are judged differently than under the legacy `.length`.
  */
 export declare function countCodePoints(value: string): number;

package/dist/types/index.js

@@ -28,15 +28,15 @@ function isStringArray(value) {
     return isArray(value) && value.every(isString);
 }
 /**
- * 文字列の長さをコードポイントで数える。
+ * Counts a string's length in code points.
  *
- * `.length` は UTF-16 のコード単位を数えるので、絵文字や星域文字が 2 と数えられる。
- * JSON Schema §6.3.1 は minLength / maxLength をコードポイントで数えると定めており、
- * 利用者が「3文字」と書くときに期待するのもコードポイントのほう。
+ * `.length` counts UTF-16 code units, so an emoji or any astral character
+ * counts as two. JSON Schema §6.3.1 defines minLength / maxLength in code
+ * points, and code points are also what someone writing "three characters"
+ * means.
  *
- * 1.x は `.length` を使っていた (docs/legacy-spec/plugin-catalog-core.md が
- * 「暗黙の挙動で、まわりに落ちるテストがある。明示的な決定にすべき」と記録している)。
- * ここでその決定をした。星域文字を含む文字列では 1.x と判定が変わる。
+ * This is a deliberate decision, not an inherited one: strings containing
+ * astral characters are judged differently than under the legacy `.length`.
  */
 function countCodePoints(value) {
     let count = 0;

package/dist/types/index.mjs

@@ -18,15 +18,15 @@ export function isStringArray(value) {
     return isArray(value) && value.every(isString);
 }
 /**
- * 文字列の長さをコードポイントで数える。
+ * Counts a string's length in code points.
  *
- * `.length` は UTF-16 のコード単位を数えるので、絵文字や星域文字が 2 と数えられる。
- * JSON Schema §6.3.1 は minLength / maxLength をコードポイントで数えると定めており、
- * 利用者が「3文字」と書くときに期待するのもコードポイントのほう。
+ * `.length` counts UTF-16 code units, so an emoji or any astral character
+ * counts as two. JSON Schema §6.3.1 defines minLength / maxLength in code
+ * points, and code points are also what someone writing "three characters"
+ * means.
  *
- * 1.x は `.length` を使っていた (docs/legacy-spec/plugin-catalog-core.md が
- * 「暗黙の挙動で、まわりに落ちるテストがある。明示的な決定にすべき」と記録している)。
- * ここでその決定をした。星域文字を含む文字列では 1.x と判定が変わる。
+ * This is a deliberate decision, not an inherited one: strings containing
+ * astral characters are judged differently than under the legacy `.length`.
  */
 export function countCodePoints(value) {
     let count = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maroonedog/luq",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Universal Model & API Definition Platform - TypeScript validation library evolving into cross-language code generation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",