@echovisionlab/geul-common 0.4.0 → 0.6.0

package/README.md

@@ -10,6 +10,29 @@ pnpm add @echovisionlab/geul-common
 The package exports TypeScript source. Consumers must support `.ts` package
 exports. `yjs` is a peer dependency.
 
+## Validation schemas and zod locale
+
+Exported validation schemas are [`zod/mini`](https://zod.dev/packages/mini)
+schemas, so bundlers tree-shake them (classic `zod` cannot be tree-shaken).
+Call `parse` and `safeParse` on them; compose them with the functional
+`zod/mini` API (`z.optional(schema)`, `schema.check(...)`) rather than classic
+method chains. Parse failures throw `z.core.$ZodError` (not the classic
+`ZodError` class); use `z.flattenError` or `z.treeifyError` to format issues.
+
+Common never configures zod globally. Custom refinement messages are always
+English, but built-in messages (wrong type, unknown key, too small, and so on)
+come from the configured zod locale, and `zod/mini` installs none by default:
+without one they fall back to `Invalid input`. Consumers that surface or log
+issue messages must configure the English locale once at startup (importing
+classic `zod` anywhere in the process also installs it):
+
+```ts
+import { config } from "zod/mini";
+import en from "zod/v4/locales/en.js";
+
+config(en());
+```
+
 ## Development
 
 ```sh

package/package.json

@@ -2,7 +2,7 @@
   "name": "@echovisionlab/geul-common",
   "description": "Shared TypeScript contracts and helpers for Geul editors, collaboration, localized content, media blocks, pages, posts, and runtime events.",
   "author": "state303 <state303@dsub.io>",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "repository": {
@@ -16,7 +16,8 @@
   "files": [
     "README.md",
     "src",
-    "!src/**/*.test.ts"
+    "!src/**/*.test.ts",
+    "!src/**/*.golden.json"
   ],
   "scripts": {
     "format": "prettier --write .",
@@ -48,6 +49,7 @@
     "./collaboration/page": "./src/collaboration/page.ts",
     "./collaboration/post": "./src/collaboration/post.ts",
     "./collaboration/post-series": "./src/collaboration/post-series.ts",
+    "./collaboration/protocol": "./src/collaboration/protocol.ts",
     "./collaboration/release": "./src/collaboration/release.ts",
     "./collaboration/runtime-events": "./src/collaboration/runtime-events.ts",
     "./collaboration/work": "./src/collaboration/work.ts",

package/src/collaboration/artist.ts

@@ -1,17 +1,15 @@
-import { z } from "zod";
-
-export const artistCollabFieldsSchema = z
-  .object({
-    status: z.enum(["draft", "published"]).optional(),
-    realName: z.string().optional(),
-    countryCode: z.string().optional(),
-    website: z.string().optional(),
-    socialLinks: z.record(z.string(), z.string()).optional(),
-    slug: z.string().optional(),
-    labelIds: z.array(z.string()).optional(),
-    parentArtistId: z.string().nullable().optional(),
-  })
-  .strict();
+import * as z from "zod/mini";
+
+export const artistCollabFieldsSchema = z.strictObject({
+  status: z.optional(z.enum(["draft", "published"])),
+  realName: z.optional(z.string()),
+  countryCode: z.optional(z.string()),
+  website: z.optional(z.string()),
+  socialLinks: z.optional(z.record(z.string(), z.string())),
+  slug: z.optional(z.string()),
+  labelIds: z.optional(z.array(z.string())),
+  parentArtistId: z.optional(z.nullable(z.string())),
+});
 
 export const ARTIST_JSON_KEYS: ReadonlySet<
   keyof z.infer<typeof artistCollabFieldsSchema>

package/src/collaboration/campaign.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod/mini";
 
 export const campaignRecipientScopeSchema = z.enum([
   "SUBSCRIBED_USERS",
@@ -9,13 +9,11 @@ export type CampaignRecipientScope = z.infer<
   typeof campaignRecipientScopeSchema
 >;
 
-export const campaignCollabFieldsSchema = z
-  .object({
-    segmentId: z.string().nullable().optional(),
-    layoutId: z.string().nullable().optional(),
-    recipientScope: campaignRecipientScopeSchema.default("SUBSCRIBED_USERS"),
-  })
-  .strict();
+export const campaignCollabFieldsSchema = z.strictObject({
+  segmentId: z.optional(z.nullable(z.string())),
+  layoutId: z.optional(z.nullable(z.string())),
+  recipientScope: z._default(campaignRecipientScopeSchema, "SUBSCRIBED_USERS"),
+});
 
 export type CampaignCollabFields = z.infer<typeof campaignCollabFieldsSchema>;
 export type CampaignFieldValue = string | null;

package/src/collaboration/document-layout.ts

@@ -1,5 +1,5 @@
 import type * as Y from "yjs";
-import { z } from "zod";
+import * as z from "zod/mini";
 
 export const DOCUMENT_LAYOUT_FIELD_KEYS = [
   "contentHeight",
@@ -7,13 +7,11 @@ export const DOCUMENT_LAYOUT_FIELD_KEYS = [
   "footer",
 ] as const;
 
-export const documentLayoutSchema = z
-  .object({
-    contentHeight: z.enum(["content", "viewport"]),
-    pageChrome: z.enum(["flow", "pinned"]),
-    footer: z.enum(["flow", "pinned"]),
-  })
-  .strict();
+export const documentLayoutSchema = z.strictObject({
+  contentHeight: z.enum(["content", "viewport"]),
+  pageChrome: z.enum(["flow", "pinned"]),
+  footer: z.enum(["flow", "pinned"]),
+});
 
 export type DocumentLayout = z.infer<typeof documentLayoutSchema>;
 

package/src/collaboration/document.ts

@@ -7,7 +7,7 @@
 
 import { CollaborativeDocumentType } from "@echovisionlab/geul-proto/secure/collaboration_pb.ts";
 import type * as Y from "yjs";
-import { z } from "zod";
+import * as z from "zod/mini";
 import { memberIdSchema } from "./member-id.ts";
 import type { BlockRoomDocumentType } from "./block-room-codec.ts";
 
@@ -115,14 +115,12 @@ export interface ParsedDocument {
   locale: string;
 }
 
-export const documentSaveOptionsSchema = z
-  .object({
-    /** Distinct authenticated Members whose edits are included in this persisted state. */
-    contributorMemberIds: z.array(memberIdSchema).optional(),
-    /** Requests a source version checkpoint after ordinary durable persistence. */
-    versionCheckpoint: z.boolean().optional(),
-  })
-  .strict();
+export const documentSaveOptionsSchema = z.strictObject({
+  /** Distinct authenticated Members whose edits are included in this persisted state. */
+  contributorMemberIds: z.optional(z.array(memberIdSchema)),
+  /** Requests a source version checkpoint after ordinary durable persistence. */
+  versionCheckpoint: z.optional(z.boolean()),
+});
 
 export type DocumentSaveOptions = z.infer<typeof documentSaveOptionsSchema>;
 

package/src/collaboration/form.ts

@@ -11,18 +11,16 @@ import {
   formValidatorMessageTarget,
 } from "@echovisionlab/geul-proto/intra/form_locale_catalog.ts";
 import * as Y from "yjs";
-import { z } from "zod";
+import * as z from "zod/mini";
 
 export const FORM_FIELDS_MAP_NAME = "form-fields";
 export const FORM_LOCALE_PRESENCE_MAP_NAME = "form-locale-presence";
 export const FORM_CANONICAL_CONTEXT_MAP_NAME = "form-canonical-context";
 
-export const formCollabFieldsSchema = z
-  .object({
-    title: z.string().optional(),
-    schema: z.unknown().optional(),
-  })
-  .strict();
+export const formCollabFieldsSchema = z.strictObject({
+  title: z.optional(z.string()),
+  schema: z.optional(z.unknown()),
+});
 
 export const FORM_JSON_KEYS: ReadonlySet<
   keyof z.infer<typeof formCollabFieldsSchema>

package/src/collaboration/label.ts

@@ -1,14 +1,12 @@
-import { z } from "zod";
-
-export const labelCollabFieldsSchema = z
-  .object({
-    slug: z.string().optional(),
-    countryCode: z.string().optional(),
-    website: z.string().optional(),
-    socialLinks: z.record(z.string(), z.string()).optional(),
-    parentLabelId: z.string().nullable().optional(),
-  })
-  .strict();
+import * as z from "zod/mini";
+
+export const labelCollabFieldsSchema = z.strictObject({
+  slug: z.optional(z.string()),
+  countryCode: z.optional(z.string()),
+  website: z.optional(z.string()),
+  socialLinks: z.optional(z.record(z.string(), z.string())),
+  parentLabelId: z.optional(z.nullable(z.string())),
+});
 
 export const LABEL_SHARED_FIELD_KEYS = Object.keys(
   labelCollabFieldsSchema.shape,

package/src/collaboration/map-theme.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod/mini";
 
 export const MAP_THEME_META_MAP_NAME = "map-theme-meta";
 export const MAP_THEME_SETTINGS_MAP_NAME = "map-theme-settings";
@@ -31,42 +31,41 @@ const calloutFieldSchema = z.enum([
   "postalCode",
 ]);
 
-const MapThemeEditingNameSchema = z.string().refine(isValidMapThemeName, {
-  message: `Map Theme name must contain 1-${MAP_THEME_NAME_MAX_LENGTH} Unicode code points`,
-});
+const MapThemeEditingNameSchema = z.string().check(
+  z.refine(isValidMapThemeName, {
+    message: `Map Theme name must contain 1-${MAP_THEME_NAME_MAX_LENGTH} Unicode code points`,
+  }),
+);
 
-const MapThemeCanonicalNameSchema = MapThemeEditingNameSchema.transform(
-  (value) => value.trim(),
+const MapThemeCanonicalNameSchema = z.pipe(
+  MapThemeEditingNameSchema,
+  z.transform((value: string) => value.trim()),
 );
 
-export const MapThemeDocumentEditingMetaSchema = z
-  .object({
-    name: MapThemeEditingNameSchema,
-  })
-  .strict();
+export const MapThemeDocumentEditingMetaSchema = z.strictObject({
+  name: MapThemeEditingNameSchema,
+});
 
-export const MapThemeDocumentMetaSchema = z
-  .object({
-    name: MapThemeCanonicalNameSchema,
-  })
-  .strict();
+export const MapThemeDocumentMetaSchema = z.strictObject({
+  name: MapThemeCanonicalNameSchema,
+});
 
 export type MapThemeDocumentMeta = z.infer<typeof MapThemeDocumentMetaSchema>;
 
 export const MAP_THEME_META_JSON_KEYS: ReadonlySet<keyof MapThemeDocumentMeta> =
   new Set([]);
 
-export const MapThemeDocumentSettingsSchema = z
-  .object({
-    calloutScale: z.number().min(0.5).max(2),
-    calloutOffsetX: z.number().int().min(-50).max(50),
-    calloutOffsetY: z.number().int().min(-50).max(50),
-    calloutFields: z.array(calloutFieldSchema).min(1).max(8),
-    showAreaLabels: z.boolean(),
-    showPoiLabels: z.boolean(),
-    attributionFontSize: z.number().int().min(9).max(14),
-  })
-  .strict();
+export const MapThemeDocumentSettingsSchema = z.strictObject({
+  calloutScale: z.number().check(z.minimum(0.5), z.maximum(2)),
+  calloutOffsetX: z.int().check(z.minimum(-50), z.maximum(50)),
+  calloutOffsetY: z.int().check(z.minimum(-50), z.maximum(50)),
+  calloutFields: z
+    .array(calloutFieldSchema)
+    .check(z.minLength(1), z.maxLength(8)),
+  showAreaLabels: z.boolean(),
+  showPoiLabels: z.boolean(),
+  attributionFontSize: z.int().check(z.minimum(9), z.maximum(14)),
+});
 
 export type MapThemeDocumentSettings = z.infer<
   typeof MapThemeDocumentSettingsSchema
@@ -101,39 +100,37 @@ export function isMapThemeColor(value: string): boolean {
   return rgba.slice(1, 4).every((channel) => Number(channel) <= 255);
 }
 
-export const MapThemeColorSchema = z
-  .string()
-  .trim()
-  .max(50)
-  .refine(isMapThemeColor, {
+export const MapThemeColorSchema = z.string().check(
+  z.trim(),
+  z.maxLength(50),
+  z.refine(isMapThemeColor, {
     message: "Invalid map theme color",
-  });
-
-export const MapThemeDocumentVariantSchema = z
-  .object({
-    backgroundColor: MapThemeColorSchema,
-    waterColor: MapThemeColorSchema,
-    landColor: MapThemeColorSchema,
-    roadColor: MapThemeColorSchema,
-    buildingFillColor: MapThemeColorSchema,
-    buildingStrokeEnabled: z.boolean(),
-    buildingStrokeColor: MapThemeColorSchema,
-    calloutLineColor: MapThemeColorSchema,
-    calloutHoverLineColor: MapThemeColorSchema,
-    calloutTextColor: MapThemeColorSchema,
-    calloutHoverTextColor: MapThemeColorSchema,
-    calloutDescriptionColor: MapThemeColorSchema,
-    calloutHoverDescriptionColor: MapThemeColorSchema,
-    calloutBackgroundColor: MapThemeColorSchema,
-    calloutHoverBackgroundColor: MapThemeColorSchema,
-    attributionColor: MapThemeColorSchema,
-    labelTextColor: MapThemeColorSchema,
-    clusterColor: MapThemeColorSchema,
-    clusterHoverColor: MapThemeColorSchema,
-    clusterTextColor: MapThemeColorSchema,
-    clusterTextHoverColor: MapThemeColorSchema,
-  })
-  .strict();
+  }),
+);
+
+export const MapThemeDocumentVariantSchema = z.strictObject({
+  backgroundColor: MapThemeColorSchema,
+  waterColor: MapThemeColorSchema,
+  landColor: MapThemeColorSchema,
+  roadColor: MapThemeColorSchema,
+  buildingFillColor: MapThemeColorSchema,
+  buildingStrokeEnabled: z.boolean(),
+  buildingStrokeColor: MapThemeColorSchema,
+  calloutLineColor: MapThemeColorSchema,
+  calloutHoverLineColor: MapThemeColorSchema,
+  calloutTextColor: MapThemeColorSchema,
+  calloutHoverTextColor: MapThemeColorSchema,
+  calloutDescriptionColor: MapThemeColorSchema,
+  calloutHoverDescriptionColor: MapThemeColorSchema,
+  calloutBackgroundColor: MapThemeColorSchema,
+  calloutHoverBackgroundColor: MapThemeColorSchema,
+  attributionColor: MapThemeColorSchema,
+  labelTextColor: MapThemeColorSchema,
+  clusterColor: MapThemeColorSchema,
+  clusterHoverColor: MapThemeColorSchema,
+  clusterTextColor: MapThemeColorSchema,
+  clusterTextHoverColor: MapThemeColorSchema,
+});
 
 export type MapThemeDocumentVariant = z.infer<
   typeof MapThemeDocumentVariantSchema
@@ -143,14 +140,12 @@ export const MAP_THEME_VARIANT_JSON_KEYS: ReadonlySet<
   keyof MapThemeDocumentVariant
 > = new Set([]);
 
-export const MapThemeDocumentSnapshotSchema = z
-  .object({
-    name: MapThemeDocumentMetaSchema.shape.name,
-    settings: MapThemeDocumentSettingsSchema,
-    lightVariant: MapThemeDocumentVariantSchema,
-    darkVariant: MapThemeDocumentVariantSchema,
-  })
-  .strict();
+export const MapThemeDocumentSnapshotSchema = z.strictObject({
+  name: MapThemeDocumentMetaSchema.shape.name,
+  settings: MapThemeDocumentSettingsSchema,
+  lightVariant: MapThemeDocumentVariantSchema,
+  darkVariant: MapThemeDocumentVariantSchema,
+});
 
 export type MapThemeDocumentSnapshot = z.infer<
   typeof MapThemeDocumentSnapshotSchema

package/src/collaboration/member-id.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod/mini";
 
 const CANONICAL_UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -6,4 +6,4 @@ const CANONICAL_UUID_PATTERN =
 /** Domain Member IDs cross service and durable-state boundaries in canonical form only. */
 export const memberIdSchema = z
   .string()
-  .regex(CANONICAL_UUID_PATTERN, "Expected a canonical Member UUID");
+  .check(z.regex(CANONICAL_UUID_PATTERN, "Expected a canonical Member UUID"));

package/src/collaboration/metadata-ai.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod/mini";
 import { memberIdSchema } from "./member-id.ts";
 
 export const metadataAiFieldSchema = z.enum(["summary"]);
@@ -11,28 +11,31 @@ export const metadataAiStatusSchema = z.enum([
 ]);
 
 export const metadataAiSharedStateSchema = z
-  .object({
+  .strictObject({
     status: metadataAiStatusSchema,
-    generationId: z.string().nullable(),
-    jobId: z.string().nullable(),
-    requesterMemberId: memberIdSchema.nullable(),
+    generationId: z.nullable(z.string()),
+    jobId: z.nullable(z.string()),
+    requesterMemberId: z.nullable(memberIdSchema),
     /** Non-authoritative Member nickname snapshot; never a Member lookup or mapping key. */
-    requesterNickname: z.string().min(1).max(100).nullable(),
+    requesterNickname: z.nullable(
+      z.string().check(z.minLength(1), z.maxLength(100)),
+    ),
     requestedFields: z.array(metadataAiFieldSchema),
     allMetadata: z.boolean(),
-    startedAt: z.number().int().nullable(),
-    updatedAt: z.number().int().nullable(),
-    orphanedAt: z.number().int().nullable(),
-    autoClearAt: z.number().int().nullable(),
+    startedAt: z.nullable(z.int()),
+    updatedAt: z.nullable(z.int()),
+    orphanedAt: z.nullable(z.int()),
+    autoClearAt: z.nullable(z.int()),
   })
-  .strict()
-  .refine(
-    (state) =>
-      state.requesterNickname === null || state.requesterMemberId !== null,
-    {
-      message: "requesterNickname requires requesterMemberId",
-      path: ["requesterNickname"],
-    },
+  .check(
+    z.refine(
+      (state) =>
+        state.requesterNickname === null || state.requesterMemberId !== null,
+      {
+        message: "requesterNickname requires requesterMemberId",
+        path: ["requesterNickname"],
+      },
+    ),
   );
 
 export const METADATA_AI_MAP_NAME = "metadata-ai";

package/src/collaboration/page.ts

@@ -1,10 +1,10 @@
-import { z } from "zod";
+import * as z from "zod/mini";
 
 export * from "./document-layout.ts";
 
 // Shared Page Yjs owns only section/column/block structure. Page settings are
 // changed through their owning DB mutations and must not be persisted here.
-export const pageCollabFieldsSchema = z.object({}).strict();
+export const pageCollabFieldsSchema = z.strictObject({});
 
 export const PAGE_SOURCE_OWNED_FIELD_KEYS = ["title", "summary"] as const;
 export const PAGE_SHARED_FIELD_KEYS = [] as const;

package/src/collaboration/post.ts

@@ -1,13 +1,11 @@
-import { z } from "zod";
-
-export const postCollabFieldsSchema = z
-  .object({
-    title: z.string().optional(),
-    summary: z.string().optional(),
-    categoryIds: z.array(z.string()).optional(),
-    tagIds: z.array(z.string()).optional(),
-  })
-  .strict();
+import * as z from "zod/mini";
+
+export const postCollabFieldsSchema = z.strictObject({
+  title: z.optional(z.string()),
+  summary: z.optional(z.string()),
+  categoryIds: z.optional(z.array(z.string())),
+  tagIds: z.optional(z.array(z.string())),
+});
 
 export const POST_JSON_KEYS: ReadonlySet<
   keyof z.infer<typeof postCollabFieldsSchema>