@ckb-ccc/core 2.0.0-next.0 → 2.0.0-next.1

package/src/utils/index.ts

@@ -1,6 +1,11 @@
 import { Zero } from "../fixedPoint/index.js";
 import { NumLike, numFrom, numToHex, type Num } from "../num/index.js";
 
+export * from "./abortSignal.js";
+export * from "./constructor.js";
+export * from "./owner/index.js";
+export * from "./proxy.js";
+
 /**
  * A type safe way to apply a transformer on a value if it's not empty.
  * @public
@@ -251,15 +256,177 @@ export async function reduceAsync<T, V>(
   return acc;
 }
 
-export function sleep(ms: NumLike) {
-  return new Promise((resolve) => setTimeout(resolve, Number(numFrom(ms))));
+/**
+ * Waits for the given duration, rejecting with the abort reason if cancelled.
+ * @public
+ */
+export function sleep(ms: NumLike, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    signal?.throwIfAborted();
+
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(signal?.reason);
+    };
+    const timeout = setTimeout(
+      () => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      },
+      Number(numFrom(ms)),
+    );
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type Constructor<T, Args extends any[] = any[]> = {
-  new (...args: Args): T;
+export type RetryOptions = {
+  /** Repeats indefinitely with this delay after the delay iterable is exhausted. */
+  repeat?: NumLike;
+  /** Cancels waiting between attempts. */
+  signal?: AbortSignal;
 };
 
+/** A result returned by a retry operation. @public */
+export type RetryResult<T> =
+  | { status: "resolved"; value: T }
+  | { status: "rejected"; error: unknown }
+  | { status: "retry"; value?: never };
+
+/** Values available to each retry attempt. @public */
+export type RetryOperationOptions<T> = {
+  /** Zero-based attempt index. */
+  index: number;
+  resolve: (value: T) => RetryResult<T>;
+  reject: (error: unknown) => RetryResult<T>;
+  next: () => RetryResult<never>;
+};
+
+function retryResolve<T>(value: T): RetryResult<T> {
+  return { status: "resolved", value };
+}
+
+function retryReject(error: unknown): RetryResult<never> {
+  return { status: "rejected", error };
+}
+
+function retryAgain(): RetryResult<never> {
+  return { status: "retry" };
+}
+
+/**
+ * Retries an asynchronous operation when it throws. The iterable supplies one
+ * delay per retry and stops retrying when it is exhausted unless `repeat` is
+ * configured. Returning `resolve(value)` or `reject(error)` settles
+ * immediately. Returning `next()` consumes the next delay without throwing
+ * an error.
+ * @public
+ */
+export async function retry<T>(
+  delays: Iterable<NumLike>,
+  operation: (
+    options: RetryOperationOptions<T>,
+  ) => PromiseLike<RetryResult<T>> | RetryResult<T>,
+  options?: RetryOptions,
+): Promise<T> {
+  const iterator = delays[Symbol.iterator]();
+  let index = 0;
+
+  while (true) {
+    options?.signal?.throwIfAborted();
+
+    let result: RetryResult<T>;
+    try {
+      result = await operation({
+        index,
+        resolve: retryResolve,
+        reject: retryReject,
+        next: retryAgain,
+      });
+      if (result.status === "retry") {
+        throw new Error("Retry limit exhausted");
+      }
+    } catch (cause) {
+      const next = iterator.next();
+      const delay = next.done ? options?.repeat : next.value;
+      if (delay === undefined) {
+        throw cause;
+      }
+      await sleep(delay, options?.signal);
+      index += 1;
+      continue;
+    }
+
+    if (result.status === "rejected") {
+      throw result.error;
+    }
+
+    return result.value;
+  }
+}
+
+/**
+ * Waits until the current browser page is visible and the browser reports it
+ * is online. This does not guarantee that a remote endpoint is reachable.
+ * Resolves immediately outside a browser and rejects with the abort reason
+ * when the optional signal is aborted.
+ * @public
+ */
+export async function waitForAvailability(signal?: AbortSignal): Promise<void> {
+  signal?.throwIfAborted();
+
+  if (
+    typeof window === "undefined" ||
+    typeof document === "undefined" ||
+    typeof navigator === "undefined"
+  ) {
+    return;
+  }
+
+  const isAvailable = () =>
+    document.visibilityState === "visible" && navigator.onLine;
+  if (isAvailable()) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+
+    function cleanup() {
+      document.removeEventListener("visibilitychange", onAvailabilityChange);
+      window.removeEventListener("online", onAvailabilityChange);
+      signal?.removeEventListener("abort", onAbort);
+    }
+
+    function onAvailabilityChange() {
+      if (settled || !isAvailable()) {
+        return;
+      }
+
+      settled = true;
+      cleanup();
+      resolve();
+    }
+
+    function onAbort() {
+      if (settled) return;
+
+      settled = true;
+      cleanup();
+      reject(signal?.reason);
+    }
+
+    document.addEventListener("visibilitychange", onAvailabilityChange);
+    window.addEventListener("online", onAvailabilityChange);
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    if (signal?.aborted) {
+      onAbort();
+    } else {
+      onAvailabilityChange();
+    }
+  });
+}
+
 /**
  * @public
  */

package/src/utils/owner/aggregated.ts

@@ -0,0 +1,56 @@
+import { Owner, OwnerMoved } from "./owner.js";
+
+// TypeScript has no existential type for heterogeneous Owner values.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Owners = readonly Owner<any>[];
+
+type OwnerValues<T extends Owners> = {
+  [K in keyof T]: T[K] extends Owner<infer U> ? U : never;
+};
+
+/**
+ * An Owner that aggregates multiple ownership claims.
+ *
+ * Disposing it attempts to release every claim and aggregates any failures.
+ *
+ * @public
+ */
+export class OwnerAggregated<T extends readonly unknown[]> extends Owner<T> {
+  private constructor(
+    protected readonly value_: T,
+    private readonly owners: readonly OwnerMoved<unknown>[],
+  ) {
+    super();
+  }
+
+  /** Moves multiple ownership claims into one Owner. */
+  static from<const TOwners extends Owners>(
+    owners: TOwners,
+  ): OwnerAggregated<OwnerValues<TOwners>> {
+    if (new Set(owners).size !== owners.length) {
+      throw new Error("Cannot aggregate the same Owner more than once");
+    }
+
+    // Validate every source before moving any of them.
+    const values = owners.map(
+      (owner): unknown => owner.value,
+    ) as OwnerValues<TOwners>;
+    const moved = owners.map((owner) => this.moveFrom(owner));
+    return new OwnerAggregated(values, moved);
+  }
+
+  protected async release(): Promise<void> {
+    const results = await Promise.allSettled(
+      this.owners.map((owner) => owner.dispose()),
+    );
+    const errors: unknown[] = [];
+    for (const result of results) {
+      if (result.status === "rejected") {
+        errors.push(result.reason as unknown);
+      }
+    }
+    if (errors.length !== 0) {
+      throw new AggregateError(errors, "Failed to dispose aggregated Owners");
+    }
+  }
+}

package/src/utils/owner/index.ts

@@ -0,0 +1,4 @@
+export * from "./aggregated.js";
+export * from "./owner.js";
+export * from "./refCount.js";
+export * from "./unique.js";

package/src/utils/owner/owner.ts

@@ -0,0 +1,141 @@
+/**
+ * An ownership claim moved out of an {@link Owner}.
+ *
+ * @public
+ */
+export class OwnerMoved<T> {
+  private disposing?: Promise<void>;
+
+  constructor(
+    /** The owned value. */
+    readonly value: T,
+    private readonly disposer: (value: T) => PromiseLike<void> | void,
+  ) {}
+
+  /** Disposes this ownership claim. */
+  dispose(): Promise<void> {
+    this.disposing ??= Promise.resolve().then(() => this.disposer(this.value));
+    return this.disposing;
+  }
+}
+
+const ownerId = Symbol.for("@ckb-ccc/core.Owner");
+
+/**
+ * Owns the lifecycle of a value.
+ *
+ * @example
+ * ```ts
+ * class ConnectionOwner extends Owner<Connection> {
+ *   constructor(protected readonly value_: Connection) {
+ *     super();
+ *   }
+ *
+ *   protected release(connection: Connection): Promise<void> {
+ *     return connection.close();
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export abstract class Owner<T> {
+  protected abstract readonly value_: T;
+
+  private readonly [ownerId] = true;
+  private disposing?: Promise<void>;
+
+  /** Whether this ownership claim has not been moved or disposed. */
+  get isValid(): boolean {
+    return this.disposing === undefined;
+  }
+
+  /** Returns whether a value implements CCC Owner semantics. */
+  static is(value: unknown): value is Owner<unknown> {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      (value as { [ownerId]?: unknown })[ownerId] === true
+    );
+  }
+
+  /**
+   * The owned value.
+   *
+   * @throws If this ownership has been moved or disposed.
+   */
+  get value(): T {
+    if (this.disposing) {
+      throw new Error("Cannot access a moved or disposed Owner");
+    }
+    return this.value_;
+  }
+
+  /**
+   * Releases this ownership claim.
+   *
+   * Implementations decide whether this disposes the value immediately or,
+   * for example, only decrements a reference count.
+   */
+  protected abstract release(value: T): PromiseLike<void> | void;
+
+  /**
+   * Disposes this ownership claim. Repeated calls are safe.
+   */
+  dispose(): Promise<void> {
+    this.disposing ??= Promise.resolve().then(() => this.release(this.value_));
+    return this.disposing;
+  }
+
+  /**
+   * Maps the owned value while transferring this ownership claim.
+   *
+   * The mapper runs before the claim is moved, so a mapper failure leaves this
+   * Owner active. After a successful mapping, this Owner is invalidated and the
+   * returned Owner retains its release semantics.
+   */
+  map<U>(mapper: (value: T) => U): Owner<U> {
+    const value = mapper(this.value);
+    return new OwnerMapped(value, this.move());
+  }
+
+  /**
+   * Moves the ownership claim out of this owner without disposing it.
+   *
+   * Access is invalidated synchronously and the moved claim retains this
+   * Owner's release semantics.
+   *
+   * @throws If this owner no longer has an ownership claim.
+   */
+  protected move(): OwnerMoved<T> {
+    if (this.disposing) {
+      throw new Error("Owner has already been moved or disposed");
+    }
+
+    this.disposing = Promise.resolve();
+
+    return new OwnerMoved(this.value_, (value) => this.release(value));
+  }
+
+  /**
+   * Moves an ownership claim between Owner implementations.
+   *
+   * @throws If the source owner has already been moved or disposed.
+   */
+  protected static moveFrom<T>(owner: Owner<T>): OwnerMoved<T> {
+    return owner.move();
+  }
+}
+
+class OwnerMapped<TValue, TSource> extends Owner<TValue> {
+  constructor(
+    protected readonly value_: TValue,
+    private readonly source: OwnerMoved<TSource>,
+  ) {
+    super();
+  }
+
+  protected release() {
+    return this.source.dispose();
+  }
+}

package/src/utils/owner/refCount.ts

@@ -0,0 +1,78 @@
+import { Owner, OwnerMoved } from "./owner.js";
+
+type OwnerRefCountState<T> = {
+  owner: OwnerMoved<T>;
+  referenceCount: number;
+};
+
+/**
+ * A reference-counted Owner for a shared value.
+ *
+ * The source ownership is disposed after the final OwnerRefCount is disposed.
+ * Each clone owns one reference and can be disposed independently.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController();
+ * const first = OwnerRefCount.new(
+ *   controller,
+ *   (controller) => controller.abort(),
+ * );
+ * const second = first.clone();
+ *
+ * await first.dispose();
+ * console.log(controller.signal.aborted); // false
+ *
+ * await second.dispose();
+ * console.log(controller.signal.aborted); // true
+ * ```
+ *
+ * @public
+ */
+export class OwnerRefCount<T> extends Owner<T> {
+  private constructor(private readonly state: OwnerRefCountState<T>) {
+    super();
+  }
+
+  protected get value_(): T {
+    return this.state.owner.value;
+  }
+
+  /** Creates the first reference-counted Owner for a value. */
+  static new<T>(
+    value: T,
+    disposer: (value: T) => PromiseLike<void> | void,
+  ): OwnerRefCount<T> {
+    return new OwnerRefCount({
+      owner: new OwnerMoved(value, disposer),
+      referenceCount: 1,
+    });
+  }
+
+  /**
+   * Moves an ownership claim into a new reference-counted Owner.
+   *
+   * @throws If the source Owner has already been moved or disposed.
+   */
+  static from<T>(owner: Owner<T>): OwnerRefCount<T> {
+    return new OwnerRefCount({
+      owner: this.moveFrom(owner),
+      referenceCount: 1,
+    });
+  }
+
+  /** Creates another Owner for the same shared value. */
+  clone(): OwnerRefCount<T> {
+    // Assert that this Owner is still active before adding a reference.
+    void this.value;
+    this.state.referenceCount += 1;
+    return new OwnerRefCount(this.state);
+  }
+
+  protected release(): Promise<void> | void {
+    this.state.referenceCount -= 1;
+    if (this.state.referenceCount === 0) {
+      return this.state.owner.dispose();
+    }
+  }
+}

package/src/utils/owner/unique.ts

@@ -0,0 +1,30 @@
+import { Owner } from "./owner.js";
+
+/**
+ * An Owner with a single, transferable ownership claim.
+ *
+ * @example
+ * ```ts
+ * const owner = new OwnerUnique(
+ *   new AbortController(),
+ *   (controller) => controller.abort(),
+ * );
+ *
+ * const signal = owner.value.signal;
+ * await owner.dispose();
+ * ```
+ *
+ * @public
+ */
+export class OwnerUnique<T> extends Owner<T> {
+  constructor(
+    protected readonly value_: T,
+    private readonly disposer: (value: T) => PromiseLike<void> | void,
+  ) {
+    super();
+  }
+
+  protected release(value: T) {
+    return this.disposer(value);
+  }
+}

package/src/utils/proxy.ts

@@ -0,0 +1,165 @@
+import type { AbstractConstructor, Constructor } from "./constructor.js";
+
+/**
+ * Utilities for creating composition wrappers.
+ *
+ * @example
+ * ```ts
+ * class Wrapper extends Proxy.Base(Client) {
+ *   static readonly [Proxy.localKeys] = ["feeRate"];
+ *   public feeRate = 1000;
+ *
+ *   request(): void {
+ *     this[Proxy.inner].request();
+ *   }
+ * }
+ *
+ * const wrapper = new Wrapper(client);
+ * ```
+ *
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace Proxy {
+  /** The property key for accessing the immediately wrapped object. */
+  export const inner = "@ckb-ccc/core.Proxy.inner";
+
+  /**
+   * The static metadata key for instance fields that belong to the wrapper.
+   * Every wrapper instance field must be listed here. Prototype members are
+   * detected automatically.
+   */
+  export const localKeys: unique symbol = Symbol.for(
+    "@ckb-ccc/core.Proxy.localKeys",
+  );
+
+  /**
+   * Creates a wrapper base that delegates non-local members to an inner instance.
+   * Its constructor accepts the inner instance and does not invoke `BaseClass`.
+   *
+   * @remarks
+   * Wrapping an abstract class may require suppressing TS2655 because its abstract
+   * members are implemented by runtime delegation.
+   *
+   * @param BaseClass - The class represented by the wrapper.
+   */
+  export function Base<BaseClass extends AbstractConstructor<object>>(
+    BaseClass: BaseClass,
+  ): Omit<BaseClass, "prototype"> &
+    Constructor<
+      InstanceType<BaseClass> & {
+        readonly [inner]: InstanceType<BaseClass>;
+      },
+      [InstanceType<BaseClass>]
+    > {
+    type T = InstanceType<BaseClass>;
+
+    class ProxyClass {
+      public readonly [inner]: T;
+
+      constructor(innerValue: T) {
+        this[inner] = innerValue;
+
+        const allLocalKeys = new Set<PropertyKey>([inner]);
+        const forwardedFunctions = new Map<
+          PropertyKey,
+          { value: unknown; wrapper: (...args: unknown[]) => unknown }
+        >();
+
+        // Members introduced between the concrete subclass and ProxyClass belong
+        // to the wrapper. Stop before ProxyClass so members inherited from Base
+        // continue to be forwarded to inner.
+        for (
+          let prototype: object | null = new.target.prototype;
+          prototype !== null && prototype !== ProxyClass.prototype;
+          prototype = Reflect.getPrototypeOf(prototype)
+        ) {
+          // Every member defined directly on this prototype belongs to the wrapper.
+          for (const property of Reflect.ownKeys(prototype)) {
+            allLocalKeys.add(property);
+          }
+
+          // Resolve the class that owns this prototype and merge the local keys
+          // declared in its static metadata.
+          const constructor = Object.getOwnPropertyDescriptor(
+            prototype,
+            "constructor",
+          )?.value as unknown;
+
+          try {
+            const metadataKeys = Object.getOwnPropertyDescriptor(
+              constructor,
+              localKeys,
+            )?.value as readonly PropertyKey[] | undefined;
+            for (const property of metadataKeys ?? []) {
+              allLocalKeys.add(property);
+            }
+          } catch {}
+        }
+
+        const isLocalProperty = (
+          target: object,
+          property: PropertyKey,
+        ): boolean =>
+          allLocalKeys.has(property) ||
+          Reflect.getOwnPropertyDescriptor(target, property) !== undefined;
+
+        return new globalThis.Proxy(this, {
+          deleteProperty: (target, property) => {
+            return Reflect.deleteProperty(
+              isLocalProperty(target, property) ? target : innerValue,
+              property,
+            );
+          },
+          get: (target, property, receiver) => {
+            const isLocal = isLocalProperty(target, property);
+            const value = Reflect.get(
+              isLocal ? target : innerValue,
+              property,
+              isLocal ? receiver : innerValue,
+            ) as unknown;
+            if (isLocal || typeof value !== "function") {
+              return value;
+            }
+
+            let cached = forwardedFunctions.get(property);
+            if (cached?.value !== value) {
+              cached = {
+                value,
+                wrapper: (...args: unknown[]): unknown =>
+                  Reflect.apply(value, innerValue, args) as unknown,
+              };
+              forwardedFunctions.set(property, cached);
+            }
+            return cached.wrapper;
+          },
+          has: (target, property) => {
+            return Reflect.has(
+              isLocalProperty(target, property) ? target : innerValue,
+              property,
+            );
+          },
+          set: (target, property, value, receiver) => {
+            const isLocal = isLocalProperty(target, property);
+            return Reflect.set(
+              isLocal ? target : innerValue,
+              property,
+              value,
+              isLocal ? receiver : innerValue,
+            );
+          },
+        });
+      }
+    }
+
+    // Preserve the runtime instance and static inheritance relationships without
+    // constructing a second BaseClass instance as the proxy target.
+    const BasePrototype = (BaseClass as unknown as { prototype: object })
+      .prototype;
+    Object.setPrototypeOf(ProxyClass.prototype, BasePrototype);
+    Object.setPrototypeOf(ProxyClass, BaseClass);
+
+    return ProxyClass as unknown as Omit<BaseClass, "prototype"> &
+      Constructor<T & { readonly [inner]: T }, [T]>;
+  }
+}

package/tsdown.config.mts

@@ -25,6 +25,7 @@ const bundleDeps = [
   "bs58check",
   "bs58", // By bs58check
   "base-x", // By bs58 - bs58check
+  "uint8array-extras",
 ] as string[];
 
 export default defineConfig(