@evolu/common 6.0.1-preview.24 → 6.0.1-preview.26

package/src/Type.ts

@@ -5,6 +5,9 @@
  * {@link Result}) instead of throwing. We either get a safely typed value or a
  * precise, composable error value telling us exactly why validation failed.
  *
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
+ * interoperability with 40+ validation-compatible tools and frameworks.
+ *
  * Why another validation library?
  *
  * - **Result-based error handling** – no exceptions for normal control flow.
@@ -196,7 +199,7 @@ export interface Type<
   Parent = T,
   /** The parent's error. */
   ParentError extends TypeError = Error,
-> {
+> extends StandardSchemaV1<Input, T> {
   readonly name: Name;
 
   /**
@@ -250,7 +253,6 @@ export interface Type<
    *
    * - When you need to convert a validation result to a nullable value
    * - When the error is not important and you just want the value or nothing
-   * - APIs that expect `T | null`
    *
    * ### Example
    *
@@ -367,8 +369,6 @@ export interface Type<
   readonly ParentError: ParentError;
 
   /**
-   * Error | ParentError
-   *
    * ### Example
    *
    * ```ts
@@ -458,7 +458,7 @@ export type InferParentError<A extends AnyType> =
     : never;
 
 /**
- * Extracts all error types (Error | ParentError) from a {@link Type}.
+ * Extracts all error types from a {@link Type}.
  *
  * @category Utilities
  */
@@ -500,6 +500,7 @@ const createType = <
     | "Parent"
     | "ParentError"
     | "Errors"
+    | "~standard"
   >,
 ): Type<Name, T, Input, Error, Parent, ParentError> => ({
   ...definition,
@@ -515,6 +516,27 @@ const createType = <
   Parent: undefined as unknown as Parent,
   ParentError: undefined as unknown as ParentError,
   Errors: undefined as unknown as Error | ParentError,
+  "~standard": {
+    version: 1,
+    vendor: "evolu",
+    validate: (value: unknown): StandardSchemaV1.Result<T> => {
+      const result = definition.fromUnknown(value);
+      if (result.ok) {
+        return { value: result.value };
+      }
+      cachedStandardSchemaFormatTypeError ??= createFormatTypeError();
+      return {
+        issues: typeErrorToStandardSchemaIssues(
+          result.error as TypeErrors<Error>,
+          cachedStandardSchemaFormatTypeError,
+        ),
+      };
+    },
+    types: {
+      input: undefined as unknown as Input,
+      output: undefined as unknown as T,
+    },
+  },
 });
 
 /**
@@ -741,7 +763,7 @@ export interface InstanceOfType<T extends abstract new (...args: any) => any>
 }
 
 export const formatInstanceOfError = createTypeErrorFormatter<InstanceOfError>(
-  (error) => `Value ${error.value} is not an instance of ${error.ctor}`,
+  (error) => `The value ${error.value} is not an instance of ${error.ctor}.`,
 );
 
 /**
@@ -1005,7 +1027,7 @@ export interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
 
 export const formatCurrencyCodeError =
   createTypeErrorFormatter<CurrencyCodeError>(
-    (error) => `Invalid currency code: ${error.value}`,
+    (error) => `Invalid currency code: ${error.value}.`,
   );
 
 /**
@@ -1125,7 +1147,7 @@ export const trimmed: BrandFactory<"Trimmed", string, TrimmedError> = (
 export interface TrimmedError extends TypeError<"Trimmed"> {}
 
 export const formatTrimmedError = createTypeErrorFormatter<TrimmedError>(
-  (error) => `A value ${error.value} is not trimmed`,
+  (error) => `The value ${error.value} must be trimmed.`,
 );
 
 /**
@@ -1170,7 +1192,7 @@ export interface MinLengthError<Min extends number = number>
 
 export const formatMinLengthError = createTypeErrorFormatter<MinLengthError>(
   (error) =>
-    `Value ${error.value} does not meet the minimum length of ${error.min}.`,
+    `The value ${error.value} does not meet the minimum length of ${error.min}.`,
 );
 
 /**
@@ -1200,7 +1222,8 @@ export interface MaxLengthError<Max extends number = number>
 }
 
 export const formatMaxLengthError = createTypeErrorFormatter<MaxLengthError>(
-  (error) => `Value ${error.value} exceeds the maximum length of ${error.max}.`,
+  (error) =>
+    `The value ${error.value} exceeds the maximum length of ${error.max}.`,
 );
 
 /**
@@ -1233,7 +1256,7 @@ export interface LengthError<Exact extends number = number>
 
 export const formatLengthError = createTypeErrorFormatter<LengthError>(
   (error) =>
-    `Value ${error.value} does not have the required length of ${error.exact}.`,
+    `The value ${error.value} does not have the required length of ${error.exact}.`,
 );
 
 /** @category String */
@@ -1295,7 +1318,7 @@ export type Mnemonic = typeof Mnemonic.Type;
 export interface MnemonicError extends TypeError<"Mnemonic"> {}
 
 export const formatMnemonicError = createTypeErrorFormatter<MnemonicError>(
-  (error) => `Invalid BIP39 mnemonic: ${error.value}`,
+  (error) => `Invalid BIP39 mnemonic: ${error.value}.`,
 );
 
 /**
@@ -1334,7 +1357,7 @@ export interface RegexError<Name extends TypeName = TypeName>
 
 export const formatRegexError = createTypeErrorFormatter<RegexError>(
   (error) =>
-    `Value ${error.value} does not match the pattern for ${error.name}: ${error.pattern}`,
+    `The value ${error.value} does not match the pattern for ${error.name}: ${error.pattern}.`,
 );
 
 /**
@@ -1400,7 +1423,7 @@ export type Base64Url = typeof Base64Url.Type;
 export interface Base64UrlError extends TypeError<"Base64Url"> {}
 
 export const formatBase64UrlError = createTypeErrorFormatter<Base64UrlError>(
-  (error) => `Value ${error.value} is not a valid Base64Url string.`,
+  (error) => `The value ${error.value} is not a valid Base64Url string.`,
 );
 
 const hasNodeBuffer = typeof globalThis.Buffer !== "undefined";
@@ -1553,7 +1576,7 @@ export type Id = typeof Id.Type;
 export interface IdError extends TypeError<"Id"> {}
 
 export const formatIdError = createTypeErrorFormatter<IdError>(
-  (error) => `Value ${error.value} is not a valid Id.`,
+  (error) => `The value ${error.value} is not a valid Id.`,
 );
 
 /**
@@ -1673,7 +1696,7 @@ export interface TableIdError<Table extends TypeName = TypeName>
 }
 
 export const formatTableIdError = createTypeErrorFormatter<TableIdError>(
-  (error) => `Invalid ${error.type} table Id: ${error.value}`,
+  (error) => `Invalid Id for table ${error.table}: ${error.value}.`,
 );
 
 /** Binary representation of an {@link Id}. */
@@ -1691,7 +1714,7 @@ export const idBytesToId = (idBytes: IdBytes): Id =>
   uint8ArrayToBase64Url(idBytes) as unknown as Id;
 
 /**
- * Positive number.
+ * Positive number (> 0).
  *
  * ### Example
  *
@@ -1714,11 +1737,11 @@ export const positive: BrandFactory<"Positive", number, PositiveError> = (
 export interface PositiveError extends TypeError<"Positive"> {}
 
 export const formatPositiveError = createTypeErrorFormatter<PositiveError>(
-  (error) => `The value ${error.value} is not positive.`,
+  (error) => `The value ${error.value} must be positive (> 0).`,
 );
 
 /**
- * Negative number.
+ * Negative number (< 0).
  *
  * ### Example
  *
@@ -1738,11 +1761,11 @@ export const negative: BrandFactory<"Negative", number, NegativeError> = (
 export interface NegativeError extends TypeError<"Negative"> {}
 
 export const formatNegativeError = createTypeErrorFormatter<NegativeError>(
-  (error) => `The value ${error.value} is not negative.`,
+  (error) => `The value ${error.value} must be negative (< 0).`,
 );
 
 /**
- * Non-positive number.
+ * Non-positive number (≤ 0).
  *
  * ### Example
  *
@@ -1767,11 +1790,11 @@ export interface NonPositiveError extends TypeError<"NonPositive"> {}
 
 export const formatNonPositiveError =
   createTypeErrorFormatter<NonPositiveError>(
-    (error) => `The value ${error.value} is not non-positive.`,
+    (error) => `The value ${error.value} must be non-positive (≤ 0).`,
   );
 
 /**
- * Non-negative number.
+ * Non-negative number (≥ 0).
  *
  * ### Example
  *
@@ -1796,7 +1819,7 @@ export interface NonNegativeError extends TypeError<"NonNegative"> {}
 
 export const formatNonNegativeError =
   createTypeErrorFormatter<NonNegativeError>(
-    (error) => `The value ${error.value} is not non-negative.`,
+    (error) => `The value ${error.value} must be non-negative (≥ 0).`,
   );
 
 /** @category Number */
@@ -1836,7 +1859,7 @@ export const int: BrandFactory<"Int", number, IntError> = (parent) =>
 export interface IntError extends TypeError<"Int"> {}
 
 export const formatIntError = createTypeErrorFormatter<IntError>(
-  (error) => `The value ${error.value} is not an integer.`,
+  (error) => `The value ${error.value} must be an integer.`,
 );
 
 /**
@@ -1982,7 +2005,7 @@ export const nonNaN: BrandFactory<"NonNaN", number, NonNaNError> = (parent) =>
 export interface NonNaNError extends TypeError<"NonNaN"> {}
 
 export const formatNonNaNError = createTypeErrorFormatter<NonNaNError>(
-  (error) => `The value ${error.value} is NaN (not a number).`,
+  () => `The value must not be NaN.`,
 );
 
 /** @category Number */
@@ -2004,7 +2027,7 @@ export const finite: BrandFactory<"Finite", number, FiniteError> = (parent) =>
 export interface FiniteError extends TypeError<"Finite"> {}
 
 export const formatFiniteError = createTypeErrorFormatter<FiniteError>(
-  (error) => `The value ${error.value} is not finite.`,
+  (error) => `The value ${error.value} must be finite.`,
 );
 
 /**
@@ -4045,8 +4068,220 @@ export const createFormatTypeError = <ExtraErrors extends TypeError = never>(
         return formatUnionError(formatTypeError)(error);
       case "Tuple":
         return formatTupleError(formatTypeError)(error);
+      default: {
+        // Fallback for unknown error types
+        const unknownError = error as TypeError;
+        return `A value ${safelyStringifyUnknownValue(unknownError.value)} is not valid for type ${unknownError.type}.`;
+      }
     }
   };
 
   return formatTypeError;
 };
+
+/**
+ * Converts an Evolu {@link TypeError} to Standard Schema V1 issues format.
+ *
+ * This function recursively converts Evolu's typed errors into the Standard
+ * Schema issue format with proper path tracking for nested structures.
+ *
+ * @category Utilities
+ */
+export const typeErrorToStandardSchemaIssues = <
+  ExtraErrors extends TypeError = never,
+>(
+  error: TypeErrors<ExtraErrors>,
+  formatTypeError: TypeErrorFormatter<TypeErrors<ExtraErrors>>,
+  path: ReadonlyArray<PropertyKey> = [],
+): ReadonlyArray<StandardSchemaV1.Issue> => {
+  if (error.type === "Array") {
+    const arrayError = error as ArrayError;
+    if (arrayError.reason.kind === "NotArray") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    return typeErrorToStandardSchemaIssues(
+      arrayError.reason.error as TypeErrors<ExtraErrors>,
+      formatTypeError,
+      [...path, arrayError.reason.index],
+    );
+  }
+
+  if (error.type === "Object") {
+    const objectError = error as ObjectError;
+    if (
+      objectError.reason.kind === "NotObject" ||
+      objectError.reason.kind === "ExtraKeys"
+    ) {
+      return [{ message: formatTypeError(error), path }];
+    }
+    const issues: Array<StandardSchemaV1.Issue> = [];
+    for (const [key, propError] of Object.entries(objectError.reason.errors)) {
+      issues.push(
+        ...typeErrorToStandardSchemaIssues(
+          propError as TypeErrors<ExtraErrors>,
+          formatTypeError,
+          [...path, key],
+        ),
+      );
+    }
+    return issues;
+  }
+
+  if (error.type === "ObjectWithRecord") {
+    const objectWithRecordError = error as ObjectWithRecordError;
+    if (objectWithRecordError.reason.kind === "NotObject") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    if (
+      objectWithRecordError.reason.kind === "IndexKey" ||
+      objectWithRecordError.reason.kind === "IndexValue"
+    ) {
+      return typeErrorToStandardSchemaIssues(
+        objectWithRecordError.reason.error as TypeErrors<ExtraErrors>,
+        formatTypeError,
+        [...path, objectWithRecordError.reason.key as PropertyKey],
+      );
+    }
+    const issues: Array<StandardSchemaV1.Issue> = [];
+    for (const [key, propError] of Object.entries(
+      objectWithRecordError.reason.errors,
+    )) {
+      issues.push(
+        ...typeErrorToStandardSchemaIssues(
+          propError as TypeErrors<ExtraErrors>,
+          formatTypeError,
+          [...path, key],
+        ),
+      );
+    }
+    return issues;
+  }
+
+  if (error.type === "Record") {
+    const recordError = error as RecordError;
+    if (recordError.reason.kind === "NotRecord") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    return typeErrorToStandardSchemaIssues(
+      recordError.reason.error as TypeErrors<ExtraErrors>,
+      formatTypeError,
+      [...path, recordError.reason.key as PropertyKey],
+    );
+  }
+
+  if (error.type === "Tuple") {
+    const tupleError = error as TupleError;
+    if (tupleError.reason.kind === "InvalidLength") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    return typeErrorToStandardSchemaIssues(
+      tupleError.reason.error as TypeErrors<ExtraErrors>,
+      formatTypeError,
+      [...path, tupleError.reason.index],
+    );
+  }
+
+  if (error.type === "Union") {
+    const unionError = error as UnionError;
+    return unionError.errors.flatMap((err) =>
+      typeErrorToStandardSchemaIssues(
+        err as TypeErrors<ExtraErrors>,
+        formatTypeError,
+        path,
+      ),
+    );
+  }
+
+  if (error.type === "Brand") {
+    const brandError = error as BrandWithoutRefineError<TypeName, TypeError>;
+    if ("parentError" in brandError) {
+      return typeErrorToStandardSchemaIssues(
+        brandError.parentError as TypeErrors<ExtraErrors>,
+        formatTypeError,
+        path,
+      );
+    }
+    return [{ message: formatTypeError(error), path }];
+  }
+
+  return [{ message: formatTypeError(error), path }];
+};
+
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (
+      value: unknown,
+    ) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["input"];
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["output"];
+}
+
+/**
+ * Shared formatter cache for Standard Schema integration - avoids circular
+ * dependency by lazily creating the formatter on first use rather than during
+ * module initialization.
+ */
+let cachedStandardSchemaFormatTypeError: TypeErrorFormatter<any> | undefined;

package/src/Types.ts

@@ -79,7 +79,7 @@ export type NullablePartial<
 export type IntentionalNever = never;
 
 /**
- * String | number | bigint | boolean | undefined | null
+ * String, number, bigint, boolean, undefined, null
  *
  * https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
  */

package/src/WebSocket.ts

@@ -4,7 +4,6 @@
  * @module
  */
 
-import { assertNoErrorInCatch } from "./Assert.js";
 import { constVoid } from "./Function.js";
 import { err, ok, Result } from "./Result.js";
 import { retry, RetryError, RetryOptions } from "./Task.js";
@@ -192,7 +191,7 @@ export const createWebSocket: CreateWebSocket = (
    * - Is rejected when a connection is closed.
    * - Is resolved when WebSocket is disposed().
    */
-  retry(
+  void retry(
     {
       ...defaultRetryOptions,
       ...retryOptions,
@@ -222,6 +221,7 @@ export const createWebSocket: CreateWebSocket = (
             ? { type: "WebSocketConnectionError", event }
             : { type: "WebSocketConnectError", event };
           onError?.(error);
+
           // Trigger reconnect only on WebSocketConnectError.
           if (error.type === "WebSocketConnectError") {
             resolve(err(error));
@@ -237,14 +237,10 @@ export const createWebSocket: CreateWebSocket = (
           onMessage?.(event.data as string | ArrayBuffer | Blob);
         };
       }),
-  )(reconnectController)
-    .then((result) => {
-      if (result.ok || result.error.type === "AbortError") return;
-      onError?.(result.error as WebSocketError);
-    })
-    .catch((error: unknown) => {
-      assertNoErrorInCatch("WebSocket retry", error);
-    });
+  )(reconnectController).then((result) => {
+    if (result.ok || result.error.type === "AbortError") return;
+    onError?.(result.error as WebSocketError);
+  });
 
   return {
     send: (data) => {

package/src/index.ts

@@ -3,6 +3,7 @@ export * from "./Assert.js";
 export * from "./BigInt.js";
 export * from "./Brand.js";
 export * from "./Buffer.js";
+export * from "./Cache.js";
 export * from "./CallbackRegistry.js";
 export * from "./Console.js";
 export * from "./Crypto.js";
@@ -10,6 +11,7 @@ export * from "./Eq.js";
 export * from "./Error.js";
 export * from "./Evolu/Public.js";
 export * from "./Function.js";
+export * from "./Identicon.js";
 export * from "./ManyToManyMap.js";
 export * from "./Number.js";
 export * from "./Object.js";