@evolu/common 8.8.0 → 8.10.0

package/src/Assert.test.ts

@@ -5,6 +5,7 @@ import type { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.ts";
 import {
   assert,
   assertConditionAfterMicrotasks,
+  assertContinuationAfterMicrotasks,
   assertEqual,
   assertEqualBytes,
   assertErr,
@@ -233,6 +234,13 @@ describe("assertConditionAfterMicrotasks", () => {
     nodeAssert.equal(callCount, 3);
   });
 
+  it("resolves without adding another microtask", async () => {
+    await assertContinuationAfterMicrotasks(
+      assertConditionAfterMicrotasks(() => true, 0),
+      1,
+    );
+  });
+
   it("rejects when the condition becomes true too early", async () => {
     await nodeAssert.rejects(
       assertConditionAfterMicrotasks(() => true, 1),
@@ -248,6 +256,49 @@ describe("assertConditionAfterMicrotasks", () => {
   });
 });
 
+describe("assertContinuationAfterMicrotasks", () => {
+  it("resolves when a fulfillment continuation runs after the exact count", async () => {
+    await assertContinuationAfterMicrotasks(Promise.resolve("done"), 1);
+  });
+
+  it("resolves when a rejection continuation runs after the exact count", async () => {
+    await assertContinuationAfterMicrotasks(
+      Promise.reject(new Error("failure")),
+      1,
+    );
+  });
+
+  it("rejects when the continuation runs too early", async () => {
+    await nodeAssert.rejects(
+      assertContinuationAfterMicrotasks(Promise.resolve("done"), 2),
+      (error: unknown) => {
+        nodeAssert.ok(error instanceof nodeAssert.AssertionError);
+        nodeAssert.match(
+          error.message,
+          /Expected condition to be false after 1 microtasks\./u,
+        );
+        nodeAssert.ok(error.stack);
+        nodeAssert.equal(
+          error.stack.includes("at assertContinuationAfterMicrotasks "),
+          false,
+        );
+        return true;
+      },
+    );
+  });
+
+  it("rejects when the continuation has not run after the exact count", async () => {
+    const promise = new Promise<void>((resolve) => {
+      queueMicrotask(resolve);
+    });
+
+    await nodeAssert.rejects(
+      assertContinuationAfterMicrotasks(promise, 1),
+      /Expected condition to be true after exactly 1 microtasks\./u,
+    );
+  });
+});
+
 describe("assertThrows", () => {
   it("compares the thrown value", () => {
     assertThrows(

package/src/Assert.ts

@@ -252,10 +252,17 @@ export const assertFalse: (value: unknown) => asserts value is false = (
  *
  * @group Assertions
  */
-export const assertConditionAfterMicrotasks = async (
+export function assertConditionAfterMicrotasks(
   condition: () => boolean,
   expectedMicrotaskCount: number,
-): Promise<void> => {
+): Promise<void>;
+export async function assertConditionAfterMicrotasks(
+  condition: () => boolean,
+  expectedMicrotaskCount: number,
+  stackStartFn: (
+    ...args: Array<never>
+  ) => unknown = assertConditionAfterMicrotasks,
+): Promise<void> {
   for (
     let microtaskCount = 0;
     microtaskCount < expectedMicrotaskCount;
@@ -269,7 +276,7 @@ export const assertConditionAfterMicrotasks = async (
         actual,
         expected: false,
         operator: "strictEqual",
-        stackStartFn: assertConditionAfterMicrotasks,
+        stackStartFn,
       },
     );
     await Promise.resolve();
@@ -283,11 +290,56 @@ export const assertConditionAfterMicrotasks = async (
       actual,
       expected: true,
       operator: "strictEqual",
-      stackStartFn: assertConditionAfterMicrotasks,
+      stackStartFn,
     },
   );
+}
+
+/**
+ * Asserts that a Promise continuation runs after exactly the specified number
+ * of microtasks.
+ *
+ * Both fulfillment and rejection count as running the continuation. Use this in
+ * tests that intentionally specify async scheduling behavior. Application code
+ * must not depend on exact microtask counts. Maintainers should review count
+ * changes because they indicate that an async pipeline changed.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertContinuationAfterMicrotasks } from "@evolu/common";
+ *
+ * await assertContinuationAfterMicrotasks(Promise.resolve("ready"), 1);
+ * ```
+ *
+ * @group Assertions
+ */
+export const assertContinuationAfterMicrotasks = async (
+  promise: Promise<unknown>,
+  expectedMicrotaskCount: number,
+): Promise<void> => {
+  let continuationCalled = false;
+
+  const markContinuationCalled = (): void => {
+    continuationCalled = true;
+  };
+
+  void promise.then(markContinuationCalled, markContinuationCalled);
+
+  await assertConditionAfterMicrotasksWithStackStartFn(
+    () => continuationCalled,
+    expectedMicrotaskCount,
+    assertContinuationAfterMicrotasks,
+  );
 };
 
+const assertConditionAfterMicrotasksWithStackStartFn =
+  assertConditionAfterMicrotasks as (
+    condition: () => boolean,
+    expectedMicrotaskCount: number,
+    stackStartFn: (...args: Array<never>) => unknown,
+  ) => Promise<void>;
+
 /**
  * Asserts that a function throws the expected value.
  *

package/src/{Binary.test.ts → Bytes.test.ts}

@@ -2,7 +2,10 @@ import { describe, it, mock } from "node:test";
 import {
   assertEqual,
   assertEqualBytes,
+  assertErr,
+  assertFalse,
   assertInstanceOf,
+  assertOk,
   assertSame,
   assertThrowsInstanceOf,
   assertTrue,
@@ -10,6 +13,16 @@ import {
 
 import {
   BufferError,
+  ByteLength,
+  ByteLengthFromString,
+  ByteSizeLiteral,
+  ByteSizeLiteralBytes,
+  ByteSizeLiteralGiB,
+  ByteSizeLiteralKiB,
+  ByteSizeLiteralMiB,
+  ByteSizeLiteralTiB,
+  byteSizeToByteLength,
+  type ByteSize,
   createBuffer,
   createRunLengthEncoder,
   decodeFlags,
@@ -25,7 +38,7 @@ import {
   encodeNonNegativeInt,
   encodeNumber,
   encodeString,
-} from "./Binary.ts";
+} from "./Bytes.ts";
 import {
   assertType,
   FiniteNumber,
@@ -34,7 +47,19 @@ import {
   Object,
   PositiveInt,
   zeroNonNegativeInt,
+  localizeTypes,
+  optional,
+  typeErrorToIssues,
+  withDefault,
+  type InferErrors,
 } from "./Type.ts";
+import { env } from "./Config.ts";
+import {
+  formatByteSizeLiteralError,
+  formatObjectError,
+  formatStringError,
+  formatIdentifierError,
+} from "./intl/cs.ts";
 
 const encodeJson = (value: unknown): Uint8Array => {
   const result = JsonValue.fromUnknown(value);
@@ -1126,3 +1151,263 @@ describe("JSON binary codec", () => {
     assertTrue(error.message.includes("Invalid MessagePack data"));
   });
 });
+
+describe("ByteLength", () => {
+  it("accepts non-negative safe integers", () => {
+    assertOk(ByteLength.fromUnknown(0), 0);
+    assertOk(ByteLength.fromUnknown(1024), 1024);
+
+    const negativeZero = ByteLength.fromUnknown(-0);
+    assertErr(negativeZero, { type: "ByteLength", value: -0 });
+    assertEqual(
+      ByteLength.formatError(negativeZero.error),
+      "The value -0 is not a byte length. Use 0 instead.",
+    );
+    assertFalse(ByteLength.is(-0));
+
+    assertErr(ByteLength.fromUnknown(-1));
+    assertErr(ByteLength.fromUnknown(1.5));
+    assertErr(ByteLength.fromUnknown("1024"));
+  });
+});
+
+describe("ByteSizeLiteral", () => {
+  it("reports its own error and retains the underlying union failure", () => {
+    for (const value of ["1MB", "", "1024KiB", 1024, null, undefined]) {
+      const result = ByteSizeLiteral.fromUnknown(value);
+      assertErr(result);
+      assertType<typeof result.error, InferErrors<typeof ByteSizeLiteral>>();
+      assertEqual(result.error.type, "ByteSizeLiteral");
+      assertSame(result.error.value, value);
+      assertEqual(result.error.cause.type, "Union");
+      assertEqual(result.error.cause.errors.length, 1);
+      assertEqual(result.error.cause.errors[0].index, 0);
+      assertEqual(result.error.cause.errors[0].error.type, "Union");
+    }
+
+    const result = ByteSizeLiteral.fromUnknown("1MB", { errors: "all" });
+    assertErr(result);
+    assertEqual(result.error.cause.errors.length, 5);
+    const message =
+      'The value "1MB" is not a byte-size literal. Use a value such as "512KiB" or "1MiB".';
+    assertEqual(ByteSizeLiteral.formatError(result.error), message);
+    assertEqual(typeErrorToIssues(ByteSizeLiteral, result.error), [
+      { path: [], message },
+    ]);
+  });
+
+  it("preserves literal types and identity encoding", () => {
+    // @ts-expect-error ByteSizeLiteral Input accepts binary-unit literals, not "1MB".
+    const _invalidInput: typeof ByteSizeLiteral.Input = "1MB";
+    assertType<
+      InferErrors<typeof ByteSizeLiteral>["type"],
+      "ByteSizeLiteral"
+    >();
+    assertEqual(ByteSizeLiteral.name, "ByteSizeLiteral");
+    assertOk(ByteSizeLiteral.from("512KiB"), "512KiB");
+    assertEqual(ByteSizeLiteral.to("512KiB"), "512KiB");
+  });
+
+  it("preserves localized messages and ENV paths through composition", async () => {
+    const { custom } = localizeTypes(
+      { Size: ByteSizeLiteral },
+      { custom: { ByteSizeLiteral: () => "Custom byte size." } },
+    );
+    const Env = env({
+      APP: { quota: withDefault(optional(custom.Size), "1MiB") },
+    });
+    const { cs } = localizeTypes(
+      { Env },
+      {
+        cs: {
+          ByteSizeLiteral: formatByteSizeLiteralError,
+          Object: formatObjectError,
+          String: formatStringError,
+          CamelCaseIdentifier: formatIdentifierError,
+        },
+      },
+    );
+    assertEqual(cs.Env.orThrow({}).quota, "1MiB");
+    const supplied = cs.Env.orThrow({ APP_QUOTA: "512KiB" });
+    assertEqual({ ...cs.Env.to(supplied) }, { APP_QUOTA: "512KiB" });
+    const result = cs.Env.fromUnknown({ APP_QUOTA: "1MB" });
+    assertErr(result);
+    const message =
+      'Hodnota "1MB" není literál velikosti v bajtech. Použijte hodnotu jako "512KiB" nebo "1MiB".';
+    assertEqual(cs.Env.formatError(result.error), message);
+    assertEqual(typeErrorToIssues(cs.Env, result.error), [
+      { path: ["APP_QUOTA"], message },
+    ]);
+    assertEqual(await cs.Env["~standard"].validate({ APP_QUOTA: "1MB" }), {
+      issues: [{ path: ["APP_QUOTA"], message }],
+    });
+    assertEqual(Env.formatError(result.error), "Custom byte size.");
+  });
+
+  it("accepts each unit within its bounds", () => {
+    for (const value of [
+      "0B",
+      "9B",
+      "10B",
+      "999B",
+      "1000B",
+      "1019B",
+      "1020B",
+      "1023B",
+    ])
+      assertOk(ByteSizeLiteralBytes.fromUnknown(value), value);
+
+    const units = [
+      ["KiB", ByteSizeLiteralKiB],
+      ["MiB", ByteSizeLiteralMiB],
+      ["GiB", ByteSizeLiteralGiB],
+      ["TiB", ByteSizeLiteralTiB],
+    ] as const;
+
+    for (const [unit, Type] of units) {
+      for (const number of [
+        "1",
+        "99",
+        "999",
+        "1000",
+        "1019",
+        "1020",
+        "1023",
+        "1.5",
+        "99.5",
+        "1023.5",
+      ]) {
+        assertOk(Type.fromUnknown(`${number}${unit}`), `${number}${unit}`);
+        assertTrue(ByteSizeLiteral.is(`${number}${unit}`));
+      }
+      for (const number of ["0", "0.5", "1.1", "1.0", "1024", "1024.5", "01"])
+        assertFalse(ByteSizeLiteral.is(`${number}${unit}`));
+    }
+  });
+
+  it("rejects other units, spacing, letter case, and redundant forms", () => {
+    for (const value of [
+      "1MB",
+      "1kib",
+      "1 KiB",
+      "1KiB ",
+      "1024B",
+      "0.5B",
+      "-1B",
+      "1",
+      "",
+    ])
+      assertFalse(ByteSizeLiteral.is(value));
+  });
+
+  it("is checked at compile time", () => {
+    const literal: ByteSizeLiteral = "1023TiB";
+    assertEqual(literal, "1023TiB");
+    assertType<
+      Extract<ByteSizeLiteral, "1023TiB" | "1000B" | "0B">,
+      "1023TiB" | "1000B" | "0B"
+    >();
+    assertType<Extract<ByteSizeLiteral, "1MB" | "1.1KiB" | "1024KiB">, never>();
+
+    // @ts-expect-error Type '"1MB"' is not assignable to type 'ByteSizeLiteral'.
+    const _decimalUnit: ByteSizeLiteral = "1MB";
+    // @ts-expect-error Type '"1.1KiB"' is not assignable to type 'ByteSizeLiteral'.
+    const _fraction: ByteSizeLiteral = "1.1KiB";
+    // @ts-expect-error Type '"1024KiB"' is not assignable to type 'ByteSizeLiteral'.
+    const _redundantUnit: ByteSizeLiteral = "1024KiB";
+    // @ts-expect-error Type 'number' is not assignable to type 'ByteSize'.
+    const _unbranded: ByteSize = 1024;
+  });
+});
+
+describe("byteSizeToByteLength", () => {
+  it("converts exactly and passes a ByteLength through", () => {
+    const cases: ReadonlyArray<readonly [ByteSizeLiteral, number]> = [
+      ["0B", 0],
+      ["1023B", 1023],
+      ["1KiB", 1024],
+      ["1.5KiB", 1536],
+      ["1023.5KiB", 1048064],
+      ["1000KiB", 1024000],
+      ["1023KiB", 1047552],
+      ["1MiB", 1048576],
+      ["1023MiB", 1072693248],
+      ["1GiB", 1073741824],
+      ["1.5GiB", 1610612736],
+      ["1023GiB", 1098437885952],
+      ["1TiB", 1099511627776],
+      ["1023TiB", 1124800395214848],
+    ];
+    for (const [literal, bytes] of cases)
+      assertEqual(byteSizeToByteLength(literal), bytes);
+
+    const result = byteSizeToByteLength("1MiB");
+    assertType<typeof result, ByteLength>();
+
+    const validated = ByteLength.orThrow(1000);
+    assertSame(byteSizeToByteLength(validated), validated);
+  });
+
+  it("asserts that a literal has a supported unit", () => {
+    const error = assertThrowsInstanceOf(
+      () => byteSizeToByteLength("1PiB" as ByteSize),
+      Error,
+    );
+    assertEqual(error.message, "Unknown byte length unit: PiB");
+  });
+});
+
+describe("ByteLengthFromString", () => {
+  it("parses a number of bytes or a literal", () => {
+    assertOk(ByteLengthFromString.fromUnknown("0"), 0);
+    assertOk(ByteLengthFromString.fromUnknown("1048576"), 1048576);
+    assertOk(ByteLengthFromString.fromUnknown("007"), 7);
+    assertOk(
+      ByteLengthFromString.fromUnknown("9007199254740991"),
+      Number.MAX_SAFE_INTEGER,
+    );
+    assertOk(ByteLengthFromString.fromUnknown("10MiB"), 10485760);
+    assertOk(ByteLengthFromString.fromUnknown("1023MiB"), 1072693248);
+    assertOk(ByteLengthFromString.fromUnknown("0B"), 0);
+    assertEqual(
+      ByteLengthFromString.to(ByteLengthFromString.orThrow("1KiB")),
+      "1024",
+    );
+    assertSame(
+      ByteLengthFromString.orThrow(
+        ByteLengthFromString.to(ByteLength.orThrow(0)),
+      ),
+      0,
+    );
+  });
+
+  it("rejects other text and unsafe numbers", () => {
+    for (const value of [
+      "",
+      "10MB",
+      "1.1KiB",
+      "1024KiB",
+      "-0",
+      "-1",
+      "1.5",
+      "1e3",
+      " 1",
+      "1KiB ",
+      "9007199254740992",
+      "9007199254740993",
+      "9".repeat(309),
+    ]) {
+      const invalid = ByteLengthFromString.fromUnknown(value);
+      assertErr(invalid, { type: "ByteLengthFromString", value });
+      assertEqual(
+        ByteLengthFromString.formatError(invalid.error),
+        `The value ${JSON.stringify(value)} is not a byte length. Use a number of bytes or a literal such as 10MiB.`,
+      );
+    }
+    assertErr(ByteLengthFromString.fromUnknown(1024), {
+      type: "TypeOf",
+      expected: "String",
+      value: 1024,
+    });
+  });
+});