@evolu/common 7.2.3 → 7.4.0

package/src/Redacted.ts

@@ -0,0 +1,118 @@
+import { assert } from "./Assert.js";
+import type { Brand } from "./Brand.js";
+import type { Eq } from "./Eq.js";
+
+/**
+ * A wrapper type that prevents sensitive values from being accidentally exposed
+ * through logging, serialization, or inspection.
+ *
+ * The wrapped value is hidden and can only be accessed explicitly via
+ * {@link revealRedacted}. All standard methods (`toString`, `toJSON`, and
+ * Node.js inspect) return `<redacted>`.
+ *
+ * For type-level distinction between different secrets, use branded types.
+ *
+ * The actual value lives in a `WeakMap`, so it never appears as a property and
+ * is automatically garbage collected when the wrapper is dropped. This is
+ * better than a class with a private field because private fields are still
+ * visible in devtools. Symbols can't be used because they don't support custom
+ * `toString`.
+ *
+ * Implements `Disposable` for automatic cleanup via the `using` syntax.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Define branded types for your secrets
+ * type ApiKey = string & Brand<"ApiKey">;
+ * type DbPassword = string & Brand<"DbPassword">;
+ *
+ * // Wrap them with Redacted for safe passing
+ * type RedactedApiKey = Redacted<ApiKey>;
+ * type RedactedDbPassword = Redacted<DbPassword>;
+ *
+ * // Create a redacted secret
+ * const apiKey: ApiKey = "secret-123" as ApiKey;
+ * const redactedKey: RedactedApiKey = createRedacted(apiKey);
+ *
+ * console.log(redactedKey); // <redacted>
+ * console.log(revealRedacted(redactedKey)); // secret-123
+ *
+ * // Type safety: RedactedApiKey ≠ RedactedDbPassword
+ * const fetchUser = (key: RedactedApiKey) => {
+ *   const value: ApiKey = revealRedacted(key);
+ *   // use value...
+ * };
+ *
+ * fetchUser(redactedKey); // ✅
+ * // fetchUser(createRedacted("x" as DbPassword)); // ❌ type error
+ *
+ * // Automatic cleanup with `using`
+ * {
+ *   using secret = createRedacted("sensitive" as ApiKey);
+ *   // ... use secret ...
+ * } // automatically wiped from memory
+ * ```
+ *
+ * @experimental
+ */
+export interface Redacted<A> extends Brand<"Redacted">, Disposable {
+  /** The inner type. Useful for inference via `typeof redacted.Type`. */
+  readonly Type: A;
+}
+
+/** Creates a {@link Redacted} wrapper for a sensitive value. */
+export const createRedacted = <A>(value: A): Redacted<A> => {
+  const redacted = Object.create(proto) as Redacted<A>;
+  registry.set(redacted, value);
+  return redacted;
+};
+
+const proto = {
+  toString: () => redactedString,
+  toJSON: () => redactedString,
+  [Symbol.for("nodejs.util.inspect.custom")]: () => redactedString,
+  [Symbol.dispose](this: Redacted<unknown>) {
+    registry.delete(this);
+  },
+};
+const redactedString = "<redacted>";
+const registry = new WeakMap<Redacted<unknown>, unknown>();
+
+/**
+ * Reveals the original value from a {@link Redacted} wrapper.
+ *
+ * This is a separate function rather than a method on {@link Redacted} to make
+ * access visually explicit and easy to grep in code reviews. Accessing
+ * sensitive values should feel intentional, not convenient.
+ */
+export const revealRedacted = <A>(redacted: Redacted<A>): A => {
+  assert(registry.has(redacted), "Redacted value was not in registry");
+  return registry.get(redacted) as A;
+};
+
+/** Checks if a value is a {@link Redacted} wrapper. */
+export const isRedacted = (value: unknown): value is Redacted<unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  Object.getPrototypeOf(value) === proto;
+
+/**
+ * Creates an {@link Eq} for {@link Redacted} values based on an equality function
+ * for the underlying type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type ApiKey = string & Brand<"ApiKey">;
+ * const eqRedactedApiKey = createEqRedacted<ApiKey>(eqString);
+ *
+ * const a = createRedacted("x" as ApiKey);
+ * const b = createRedacted("x" as ApiKey);
+ * eqRedactedApiKey(a, b); // true
+ * ```
+ */
+export const createEqRedacted =
+  <A>(eq: Eq<A>): Eq<Redacted<A>> =>
+  (x, y) =>
+    eq(revealRedacted(x), revealRedacted(y));

package/src/Result.ts

@@ -1,3 +1,5 @@
+import type { Task } from "./Task.js";
+
 /**
  * The problem with throwing an exception in JavaScript is that the caught error
  * is always of an unknown type. The unknown type is a problem because we can't
@@ -82,19 +84,22 @@
  * };
  * ```
  *
+ * For lazy, cancellable async operations, see {@link Task}.
+ *
  * ### Naming convention
  *
- * - For values: `const user = getUser()`
- * - For a single void operation: `const result = foo()`
- * - For multiple void operations: use descriptive names for all
+ * - **For values you need:** use a name without Result suffix (`user`, `config`)
+ * - **For void operations:** use `result` (no value to name)
+ *
+ * For multiple void operations, use block scopes to avoid potentially long
+ * names like `createBaseTablesResult`, `createRelayTablesResult`, or counters
+ * like `result1`, `result2`:
  *
  * ```ts
  * const processUser = () => {
- *   // we have a value
  *   const user = getUser();
  *   if (!user.ok) return user;
  *
- *   // single void operation
  *   const result = saveToDatabase(user.value);
  *   if (!result.ok) return result;
  *
@@ -102,12 +107,15 @@
  * };
  *
  * const setupDatabase = () => {
- *   // multiple void operations - use descriptive names
- *   const baseTables = createBaseTables();
- *   if (!baseTables.ok) return baseTables;
- *
- *   const relayTables = createRelayTables();
- *   if (!relayTables.ok) return relayTables;
+ *   // Multiple void operations - use block scopes to avoid name clash
+ *   {
+ *     const result = createBaseTables();
+ *     if (!result.ok) return result;
+ *   }
+ *   {
+ *     const result = createRelayTables();
+ *     if (!result.ok) return result;
+ *   }
  *
  *   return ok();
  * };
@@ -124,30 +132,31 @@
  * schema, and initializes the database, stopping on the first error:
  *
  * ```ts
- * const resetResult = deps.sqlite.transaction(() => {
- *   const dropAllTablesResult = dropAllTables(deps);
- *   if (!dropAllTablesResult.ok) return dropAllTablesResult;
+ * const result = deps.sqlite.transaction(() => {
+ *   const result = dropAllTables(deps);
+ *   if (!result.ok) return result;
  *
  *   if (message.restore) {
  *     const dbSchema = getDbSchema(deps)();
  *     if (!dbSchema.ok) return dbSchema;
  *
- *     const ensureDbSchemaResult = ensureDbSchema(deps)(
- *       message.restore.dbSchema,
- *       dbSchema.value,
- *     );
- *     if (!ensureDbSchemaResult.ok) return ensureDbSchemaResult;
- *
- *     const initializeDbResult = initializeDb(deps)(
- *       message.restore.mnemonic,
- *     );
- *     if (!initializeDbResult.ok) return initializeDbResult;
+ *     {
+ *       const result = ensureDbSchema(deps)(
+ *         message.restore.dbSchema,
+ *         dbSchema.value,
+ *       );
+ *       if (!result.ok) return result;
+ *     }
+ *     {
+ *       const result = initializeDb(deps)(message.restore.mnemonic);
+ *       if (!result.ok) return result;
+ *     }
  *   }
  *   return ok();
  * });
  *
- * if (!resetResult.ok) {
- *   deps.postMessage({ type: "onError", error: resetResult.error });
+ * if (!result.ok) {
+ *   deps.postMessage({ type: "onError", error: result.error });
  *   return;
  * }
  * ```
@@ -254,13 +263,13 @@
  * ```ts
  * // ✅ Safe to return void - unsafe code is wrapped and error is handled
  * const processData = (data: string): void => {
- *   const parseResult = trySync(
+ *   const result = trySync(
  *     () => JSON.parse(data),
  *     (error) => ({ type: "ParseError", message: String(error) }),
  *   );
  *
- *   if (!parseResult.ok) {
- *     logError(parseResult.error);
+ *   if (!result.ok) {
+ *     logError(result.error);
  *     return;
  *   }
  *

package/src/Sqlite.ts

@@ -2,6 +2,7 @@ import { Brand } from "./Brand.js";
 import { createLruCache } from "./Cache.js";
 import { ConsoleDep } from "./Console.js";
 import { EncryptionKey } from "./Crypto.js";
+import { Eq, eqArrayNumber } from "./Eq.js";
 import { createTransferableError, TransferableError } from "./Error.js";
 import { err, ok, Result, tryAsync, trySync } from "./Result.js";
 import {
@@ -34,8 +35,8 @@ export interface CreateSqliteDriverDep {
 }
 
 export interface SqliteDriverOptions {
-  memory?: boolean;
-  encryptionKey?: EncryptionKey | undefined;
+  readonly memory?: boolean;
+  readonly encryptionKey?: EncryptionKey | undefined;
 }
 
 /**
@@ -75,7 +76,7 @@ export interface SqliteQuery {
 }
 
 /** A type representing a sanitized SQL string. */
-export type SafeSql = string & Brand<"TimestampString">;
+export type SafeSql = string & Brand<"SafeSql">;
 
 /**
  * A value that can be stored in Sqlite.
@@ -86,6 +87,16 @@ export type SafeSql = string & Brand<"TimestampString">;
 export const SqliteValue = union(Null, String, Number, Uint8Array);
 export type SqliteValue = typeof SqliteValue.Type;
 
+export const eqSqliteValue: Eq<SqliteValue> = (x, y) => {
+  if (
+    x instanceof globalThis.Uint8Array &&
+    y instanceof globalThis.Uint8Array
+  ) {
+    return eqArrayNumber(x, y);
+  }
+  return x === y;
+};
+
 export interface SqliteQueryOptions {
   /**
    * If set to `true`, logs the time taken to execute the SQL query. Useful for
@@ -292,13 +303,13 @@ export const createPreparedStatementsCache = <P>(
 };
 
 export interface SqlIdentifier {
-  type: "SqlIdentifier";
-  sql: SafeSql;
+  readonly type: "SqlIdentifier";
+  readonly sql: SafeSql;
 }
 
 export interface RawSql {
-  type: "RawSql";
-  sql: string;
+  readonly type: "RawSql";
+  readonly sql: string;
 }
 
 export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;

package/src/Task.ts

@@ -570,10 +570,12 @@ export const retry = <T, E>(
       }
 
       // Wait before retry
-      const delayResult = await wait(NonNegativeInt.orThrow(delay))(context);
-      if (!delayResult.ok) {
-        // If delay was aborted, return AbortError (will be handled by toTask)
-        return delayResult;
+      {
+        const result = await wait(NonNegativeInt.orThrow(delay))(context);
+        if (!result.ok) {
+          // If delay was aborted, return AbortError (will be handled by toTask)
+          return result;
+        }
       }
     }
   });

package/src/Type.ts

@@ -1,6 +1,19 @@
+import { utf8ToBytes } from "@noble/ciphers/utils.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import * as bip39 from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { pack } from "msgpackr";
+import type { Brand } from "./Brand.js";
+import type { RandomBytesDep } from "./Crypto.js";
+import { isPlainObject } from "./Object.js";
+import { hasNodeBuffer } from "./Platform.js";
+import { err, getOrNull, getOrThrow, ok, Result, trySync } from "./Result.js";
+import { safelyStringifyUnknownValue } from "./String.js";
+import type { TimeDep } from "./Time.js";
+import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
+import { IntentionalNever } from "./Types.js";
+
 /**
- * Runtime types
- *
  * Evolu {@link Type} is like a type guard that returns typed errors (via
  * {@link Result}) instead of throwing. We either get a safely typed value or a
  * composable typed error telling us exactly why validation failed.
@@ -197,25 +210,7 @@
  * ```
  *
  * Note `minLength` and `maxLength` are curried because they are factories.
- *
- * @module
  */
-
-import { utf8ToBytes } from "@noble/ciphers/utils.js";
-import { sha256 } from "@noble/hashes/sha2.js";
-import * as bip39 from "@scure/bip39";
-import { wordlist } from "@scure/bip39/wordlists/english.js";
-import { pack } from "msgpackr";
-import type { Brand } from "./Brand.js";
-import { type RandomBytesDep } from "./Crypto.js";
-import { isPlainObject } from "./Object.js";
-import { hasNodeBuffer } from "./Platform.js";
-import { err, getOrNull, getOrThrow, ok, Result, trySync } from "./Result.js";
-import { safelyStringifyUnknownValue } from "./String.js";
-import type { TimeDep } from "./Time.js";
-import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
-import { IntentionalNever } from "./Types.js";
-
 export interface Type<
   Name extends TypeName,
   /** The type this Type resolves to. */
@@ -2391,6 +2386,124 @@ export const formatArrayError = <Error extends TypeError>(
     }
   });
 
+/**
+ * Set of a specific {@link Type}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const NumberSet = set(Number);
+ *
+ * const result1 = NumberSet.from(new Set([1, 2, 3])); // ok(Set { 1, 2, 3 })
+ * const result2 = NumberSet.from(new Set(["a", "b"])); // err(...)
+ * ```
+ *
+ * @category Base Factories
+ */
+export const set = <ElementType extends AnyType>(
+  element: ElementType,
+): SetType<ElementType> => {
+  const fromUnknown = (
+    value: unknown,
+  ): Result<
+    ReadonlySet<InferType<ElementType>>,
+    SetError<InferErrors<ElementType>>
+  > => {
+    if (!(value instanceof globalThis.Set)) {
+      return err<SetError<InferErrors<ElementType>>>({
+        type: "Set",
+        value,
+        reason: { kind: "NotSet" },
+      });
+    }
+
+    let index = 0;
+    for (const item of value) {
+      const elementResult = element.fromUnknown(item);
+      if (!elementResult.ok) {
+        return err<SetError<InferErrors<ElementType>>>({
+          type: "Set",
+          value,
+          reason: {
+            kind: "Element",
+            index,
+            error: elementResult.error as InferErrors<ElementType>,
+          },
+        });
+      }
+      index++;
+    }
+
+    return ok(value as ReadonlySet<InferType<ElementType>>);
+  };
+
+  const fromParent = (
+    value: ReadonlySet<InferParent<ElementType>>,
+  ): Result<
+    ReadonlySet<InferType<ElementType>>,
+    SetError<InferError<ElementType>>
+  > => {
+    let index = 0;
+    for (const item of value) {
+      const elementResult = element.fromParent(item);
+      if (!elementResult.ok) {
+        return err({
+          type: "Set",
+          value,
+          reason: {
+            kind: "Element",
+            index,
+            error: elementResult.error as InferError<ElementType>,
+          },
+        });
+      }
+      index++;
+    }
+    return ok(value as ReadonlySet<InferType<ElementType>>);
+  };
+
+  return {
+    ...createType("Set", { fromUnknown, fromParent }),
+    element,
+  };
+};
+
+/** SetType extends Type with an additional `element` property for reflection. */
+export interface SetType<ElementType extends AnyType>
+  extends Type<
+    "Set",
+    ReadonlySet<InferType<ElementType>>,
+    ReadonlySet<InferInput<ElementType>>,
+    SetError<InferError<ElementType>>,
+    ReadonlySet<InferParent<ElementType>>,
+    SetError<InferParentError<ElementType>>
+  > {
+  readonly element: ElementType;
+}
+
+export interface SetError<Error extends TypeError = TypeError>
+  extends TypeErrorWithReason<
+    "Set",
+    | { readonly kind: "NotSet" }
+    | {
+        readonly kind: "Element";
+        readonly index: number;
+        readonly error: Error;
+      }
+  > {}
+
+export const formatSetError = <Error extends TypeError>(
+  formatTypeError: TypeErrorFormatter<Error>,
+): TypeErrorFormatter<SetError<Error>> =>
+  createTypeErrorFormatter((error) => {
+    switch (error.reason.kind) {
+      case "NotSet":
+        return `Expected a Set but received ${error.value}.`;
+      case "Element":
+        return `Invalid element at index ${error.reason.index}: ${formatTypeError(error.reason.error)}`;
+    }
+  });
+
 /**
  * Record of a key {@link Type} and value {@link Type}.
  *
@@ -3970,6 +4083,7 @@ export type TypeErrors<ExtraErrors extends TypeError = never> =
   | ExtraErrors
   // Composite errors
   | ArrayError<TypeErrors<ExtraErrors>>
+  | SetError<TypeErrors<ExtraErrors>>
   | RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>>
   | ObjectError<Record<string, TypeErrors<ExtraErrors>>>
   | ObjectWithRecordError<
@@ -4154,6 +4268,8 @@ export const createFormatTypeError = <ExtraErrors extends TypeError = never>(
         return formatSimplePasswordError(formatTypeError)(error);
       case "Array":
         return formatArrayError(formatTypeError)(error);
+      case "Set":
+        return formatSetError(formatTypeError)(error);
       case "Record":
         return formatRecordError(formatTypeError)(error);
       case "Object":
@@ -4202,6 +4318,18 @@ export const typeErrorToStandardSchemaIssues = <
     );
   }
 
+  if (error.type === "Set") {
+    const setError = error as SetError;
+    if (setError.reason.kind === "NotSet") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    return typeErrorToStandardSchemaIssues(
+      setError.reason.error as TypeErrors<ExtraErrors>,
+      formatTypeError,
+      [...path, setError.reason.index],
+    );
+  }
+
   if (error.type === "Object") {
     const objectError = error as ObjectError;
     if (

package/src/index.ts

@@ -18,6 +18,7 @@ export * from "./Object.js";
 export * from "./Order.js";
 export * from "./Platform.js";
 export * from "./Random.js";
+export * from "./Redacted.js";
 export * from "./Ref.js";
 export * from "./Relation.js";
 export * from "./Resources.js";