@effectstream/utils 0.100.0

package/src/runtime-spawn.ts

@@ -0,0 +1,188 @@
+/**
+ * Process spawn abstraction using node:child_process.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+
+/** Result of a spawned process. stdout/stderr are Web ReadableStreams so they can be pipeTo()'d. */
+export interface SpawnChild {
+  readonly pid: number;
+  /** Present when options.stdin === "piped". */
+  readonly stdin?: WritableStream<Uint8Array>;
+  readonly stdout: ReadableStream<Uint8Array>;
+  readonly stderr: ReadableStream<Uint8Array>;
+  readonly status: Promise<{
+    success: boolean;
+    code?: number;
+    signal?: string;
+  }>;
+  kill(signal?: NodeJS.Signals): void;
+  ref(): void;
+}
+
+export interface SpawnOptions {
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  signal?: AbortSignal;
+  stdin?: "inherit" | "piped" | "null";
+  stdout?: "inherit" | "piped" | "null";
+  stderr?: "inherit" | "piped" | "null";
+}
+
+/** Output from a completed process (for spawnOutput). */
+export interface SpawnOutputResult {
+  stdout: Uint8Array;
+  stderr: Uint8Array;
+  success: boolean;
+  code?: number;
+  signal?: string;
+}
+
+/** Empty stream used when stdio is "inherit" so callers can always use pipeTo. */
+function emptyReadableStream(): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.close();
+    },
+  });
+}
+
+/**
+ * Spawn a child process. Returns a handle with Web ReadableStreams for stdout/stderr
+ * so they can be used with pipeTo() in any runtime.
+ */
+export function spawn(command: string, options: SpawnOptions = {}): SpawnChild {
+  const args = options.args ?? [];
+  const stdio: ("inherit" | "pipe" | "ignore")[] = [
+    options.stdin === "piped"
+      ? "pipe"
+      : options.stdin === "null"
+        ? "ignore"
+        : "inherit",
+    options.stdout === "piped"
+      ? "pipe"
+      : options.stdout === "null"
+        ? "ignore"
+        : "inherit",
+    options.stderr === "piped"
+      ? "pipe"
+      : options.stderr === "null"
+        ? "ignore"
+        : "inherit",
+  ];
+
+  const cp = nodeSpawn(command, args, {
+    cwd: options.cwd,
+    env: { ...process.env, ...options.env, FORCE_COLOR: "true" },
+    stdio,
+    signal: options.signal,
+  });
+
+  const stdout: ReadableStream<Uint8Array> =
+    options.stdout === "piped" && cp.stdout
+      ? (Readable.toWeb(cp.stdout) as unknown as ReadableStream<Uint8Array>)
+      : emptyReadableStream();
+  const stderr: ReadableStream<Uint8Array> =
+    options.stderr === "piped" && cp.stderr
+      ? (Readable.toWeb(cp.stderr) as unknown as ReadableStream<Uint8Array>)
+      : emptyReadableStream();
+
+  const status = new Promise<{
+    success: boolean;
+    code?: number;
+    signal?: string;
+  }>((resolve) => {
+    cp.on("close", (code: number | null, signal: string | null) => {
+      resolve({
+        success: code === 0,
+        code: code ?? undefined,
+        signal: signal ?? undefined,
+      });
+    });
+  });
+
+  let stdinStream: WritableStream<Uint8Array> | undefined;
+  if (options.stdin === "piped" && cp.stdin) {
+    stdinStream = Writable.toWeb(cp.stdin) as WritableStream<Uint8Array>;
+  }
+
+  return {
+    get pid() {
+      return cp.pid ?? 0;
+    },
+    stdin: stdinStream,
+    stdout,
+    stderr,
+    status,
+    kill(signal?: NodeJS.Signals) {
+      cp.kill(signal ?? "SIGTERM");
+    },
+    ref() {
+      if (typeof cp.ref === "function") cp.ref();
+    },
+  };
+}
+
+/**
+ * Run a command and wait for it to complete, returning collected stdout/stderr.
+ * Use for short-lived commands (e.g. tmux install, kill-server).
+ */
+export async function spawnOutput(
+  command: string,
+  options: SpawnOptions & { stdinInput?: Uint8Array } = {},
+): Promise<SpawnOutputResult> {
+  const { stdinInput, ...spawnOpts } = options;
+  const useStdin = stdinInput != null;
+  const child = spawn(command, {
+    ...spawnOpts,
+    stdin: useStdin ? "piped" : spawnOpts.stdin,
+    stdout: "piped",
+    stderr: "piped",
+  });
+
+  if (useStdin && child.stdin) {
+    const writer = child.stdin.getWriter();
+    await writer.write(stdinInput);
+    await writer.close();
+  }
+
+  const [stdout, stderr, status] = await Promise.all([
+    streamToUint8Array(child.stdout),
+    streamToUint8Array(child.stderr),
+    child.status,
+  ]);
+
+  return {
+    stdout,
+    stderr,
+    success: status.success,
+    code: status.code,
+    signal: status.signal,
+  };
+}
+
+async function streamToUint8Array(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const total = chunks.reduce((n, c) => n + c.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.length;
+  }
+  return out;
+}

package/src/runtime.ts

@@ -0,0 +1,89 @@
+type RuntimeEnvironment = 'backend' | 'frontend' | 'unknown';
+type Runtime = 'node' | 'deno' | 'bun' | 'browser' | 'unknown';
+
+export function getRuntime(): {runtime: Runtime, environment: RuntimeEnvironment} {
+  // Check for Deno
+  // @ts-ignore: Deno is added to global scope in Deno environments
+  if (typeof Deno !== 'undefined') {
+    return { runtime: 'deno', environment: 'backend' };
+  }
+
+  // Check for Bun
+  // @ts-ignore: Bun is added to global scope in Bun environments
+  if (typeof Bun !== 'undefined') {
+    return { runtime: 'bun', environment: 'backend' };
+  }
+
+  // Check for Node.js
+  // Node environments have a `process` object with versions
+  if (
+    typeof process !== 'undefined' &&
+    (process as any).versions &&
+    (process as any).versions.node
+  ) {
+    return { runtime: 'node', environment: 'backend' };
+  }
+
+  // Check for Browser
+  // Browsers typically have `window` and `document`
+  if (
+    typeof window !== 'undefined' &&
+    // @ts-ignore: document is added to global scope in browser environments
+    typeof document !== 'undefined'
+  ) {
+    return { runtime: 'browser', environment: 'frontend' };
+  }
+
+  return { runtime: 'unknown', environment: 'unknown' };
+}
+
+/**
+ * Helpers for common process operations.
+ */
+
+/** Get environment variable. */
+export function getEnv(key: string): string | undefined {
+  return process.env[key];
+}
+
+/** Set environment variable. */
+export function setEnv(key: string, value: string): void {
+  process.env[key] = value;
+}
+
+/** CLI arguments (argv without script path). */
+export function args(): string[] {
+  return process.argv.slice(2);
+}
+
+/** Exit process with code. */
+export function exit(code: number): never {
+  return process.exit(code);
+}
+
+/** Current working directory. */
+export function cwd(): string {
+  return process.cwd();
+}
+
+/** Terminal size when available. */
+export function consoleSize(): { columns: number; rows: number } {
+  return {
+    columns: process.stdout.columns ?? 80,
+    rows: (process.stdout as any).rows ?? 24,
+  };
+}
+
+/** Set process exit code (for graceful shutdown). */
+export function setExitCode(code: number): void {
+  process.exitCode = code;
+}
+
+/** Check if error is "file/dir not found". */
+export function isNotFoundError(err: unknown): boolean {
+  if (err && typeof err === "object") {
+    const e = err as { code?: string };
+    if (e.code === "ENOENT") return true;
+  }
+  return false;
+}

package/src/types/json-query.ts

@@ -0,0 +1,36 @@
+export type ErrorCode = number;
+export type ErrorMessageMapping = Record<ErrorCode, string>;
+
+export type ErrorMessageFxn = (errorCode: ErrorCode) => string;
+
+export interface SuccessfulResultMessage {
+  success: true;
+  message: string;
+}
+
+export interface SuccessfulResult<T> {
+  success: true;
+  result: T;
+}
+
+export interface FailedResult {
+  success: false;
+  errorMessage: string;
+  errorCode?: number;
+}
+
+export type Result<T> = SuccessfulResult<T> | FailedResult;
+
+export type InternalServerErrorResult = FailedResult;
+
+/** comes from the `tsoa` package, but we don't want it as a dependency just for this type  */
+export interface FieldErrors {
+  [name: string]: {
+    message: string;
+    value?: any;
+  };
+}
+export interface ValidateErrorResult {
+  message: "Validation Failed";
+  details?: FieldErrors;
+}

package/src/types/misc.ts

@@ -0,0 +1,173 @@
+import type { TObject } from "@sinclair/typebox";
+import type { EvmAddress } from "./nominal.ts";
+
+export type IntersectObject<T, Obj> = T extends TObject<infer O>
+  ? TObject<ShallowMergeIntersects<O & Obj>>
+  : never;
+
+// TODO: this probably doesn't belong in this file
+export type TransactionTemplate = {
+  data: string;
+  to: EvmAddress;
+  gasPrice: string;
+};
+
+/**
+ * @description Combines members of an intersection into a readable type.
+ *
+ * @see {@link https://twitter.com/Riyaadh_Abr/status/1622736576303312899/photo/1}
+ * @example
+ * MergeIntersects<{ a: string } & { b: string } & { c: number, d: bigint }>
+ * => { a: string, b: string, c: number, d: bigint }
+ */
+export type MergeIntersects<T> = T extends
+  | Record<string, unknown>
+  | readonly Record<string, unknown>[]
+  ? T extends infer Obj ? { [K in keyof Obj]: MergeIntersects<Obj[K]> }
+  : never
+  : T;
+
+/**
+ * Same as the above, but shallow (not recursive)
+ * This is useful if you don't want Typescript to expand an underlying type
+ *
+ * ex: avoid { foo: FooType } turning into { foo: { a: string, b: string } }
+ */
+export type ShallowMergeIntersects<T> =
+  & {
+    [K in keyof T]: T[K];
+  }
+  & {};
+
+/**
+ * Flips an object so key are values and values are keys
+ *
+ * ex: Record<A, B> becomes Partial<Record<B, A>>
+ */
+export type FlipObject<T extends Record<any, any>> = {
+  [Value in T[keyof T]]: keyof {
+    [Key in keyof T as Value extends T[Key] ? Key : never]: any;
+  };
+};
+
+export type NoUndefinedField<T> = { [P in keyof T]-?: NonNullable<T[P]> };
+
+export type ElementOf<T extends readonly any[]> = T extends (infer Elem)[]
+  ? Elem
+  : never;
+export type ValueOf<T> = T[keyof T];
+
+export type Satisfies<Base, T> = T extends Base ? true : false;
+
+export type RemoveNeverEntries<T extends Record<any, any>> = {
+  [K in keyof T as T[K] extends never ? never : K]: T[K];
+};
+export type IdxOf<T> = { [idx in keyof T]: idx }[any];
+
+export type RemoveUnknown<T> = unknown extends T
+  ? (T extends unknown ? never : T)
+  : T;
+
+type ImmutablePrimitive =
+  | undefined
+  | null
+  | boolean
+  | string
+  | number
+  | Function;
+export type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+export type DeepMutable<T> = T extends ImmutablePrimitive ? T
+  : T extends ReadonlyArray<infer U> ? Array<DeepMutable<U>>
+  : T extends ReadonlySet<infer U> ? Set<DeepMutable<U>>
+  : T extends ReadonlyMap<infer K, infer V>
+    ? Map<DeepMutable<K>, DeepMutable<V>>
+  : T extends Function ? T
+  : T extends object ? { -readonly [K in keyof T]: DeepMutable<T[K]> }
+  : T;
+export type DeepReadonly<T> = T extends ImmutablePrimitive ? T
+  : T extends Array<infer U> ? ReadonlyArray<DeepReadonly<U>>
+  : T extends Map<infer K, infer V>
+    ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>
+  : T extends Set<infer M> ? ReadonlySet<DeepReadonly<M>>
+  : {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+  };
+
+export type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends (
+    k: infer I extends U,
+  ) => void ? I
+    : never;
+
+const __TypeError = Symbol("OpaqueTypeError");
+type TypeError<BaseType extends string> = BaseType & {
+  readonly [__TypeError]: BaseType;
+};
+/**
+ * Prints custom error message
+ * Taken from https://github.com/wevm/abitype/blob/main/packages/abitype/src/types.ts#L11
+ *
+ * @param messages - Error message
+ * @returns Custom error message
+ *
+ * @example
+ * type Result = Error<'Custom error message'>
+ * //   ^? type Result = ['Error: Custom error message']
+ */
+export type TypeErrorMessage<messages extends string | string[]> =
+  messages extends string ? TypeError<messages>
+    : {
+      [key in keyof messages]: messages[key] extends
+        infer message extends string ? TypeError<message>
+        : never;
+    };
+
+/**
+ * Types that Typescript allows inside a string template
+ */
+export type Stringifiable =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined;
+
+/**
+ * Turns an Object whose keys are numbers into an equivalent tuple
+ * WARNING: This ONLY works if the keys are consecutive numbers starting from 0
+ */
+export type ToTupleSimple<
+  T extends { [key: number]: any },
+  Acc extends any[] = [],
+> = Acc["length"] extends keyof T ? ToTupleSimple<T, [...Acc, T[Acc["length"]]]>
+  : Acc;
+
+// Helper type to build a tuple up to a given length `N`, inserting `never` for missing entries
+type BuildTuple<
+  T extends { [key: number]: any },
+  MaxSize extends number,
+  Acc extends any[] = [],
+> = Acc["length"] extends MaxSize ? Acc
+  : BuildTuple<
+    T,
+    MaxSize,
+    [...Acc, Acc["length"] extends keyof T ? T[Acc["length"]] : never]
+  >;
+
+// Helper type to filter out `never` values from a tuple
+type FilterNeverArray<T extends any[]> = T extends [infer First, ...infer Rest]
+  ? [First] extends [never] ? FilterNeverArray<Rest>
+  : [First, ...FilterNeverArray<Rest>]
+  : [];
+
+/**
+ * Turns an Object whose keys are numbers into an equivalent tuple
+ * WARNING: This supports objects that are missing entries (not consecutive numbers starting from 0)
+ *          However, you MUST specify the maximum value in the object keys instead
+ *          This is required since Typescript doesn't easily support artihmetic at the type level
+ */
+export type ToTupleComplex<
+  T extends { [key: number]: any },
+  MaxSize extends number,
+> = FilterNeverArray<BuildTuple<T, MaxSize>>;

package/src/types/mod.ts

@@ -0,0 +1,6 @@
+export type * from "./misc.ts";
+export type * from "./json-query.ts";
+export type * from "./nominal.ts";
+export * from "./typebox-helpers.ts";
+export * from "./utils.ts";
+export * from "./validators/mod.ts";

package/src/types/nominal.ts

@@ -0,0 +1,168 @@
+import type { FastFlavor } from "@coderspirit/nominal";
+
+/**
+ * TODO: remove any instance of this in the codebase
+ * Note: often this is uncertainty between HexString0x and HexStringNo0x
+ */
+export type UnknownFormat = string;
+
+export type URI = FastFlavor<string, "Uri">;
+
+export type Caip2 = FastFlavor<string, "Caip2">;
+/**
+ * TODO: probably best to make this more granular to different cryptographic schemes
+ *       esp. since some return 0x and others don't
+ */
+export type EvmSignature = FastFlavor<HexString0x, "EvmSignature">;
+export type GenericSignature = FastFlavor<string, "OtherSignature">;
+export type Signature =
+  | EvmSignature
+  | GenericSignature
+  | MidnightSignature
+  ;
+
+export type VersionString = `${number}.${number}.${number}`;
+
+// TODO: should probably differentiate between block numbers of different networks
+//       and maybe even Paima block number / emulated block number
+export type EffectstreamBlockNumber = FastFlavor<number, "EffectstreamBlockNumber">;
+export type EvmBlockNumber = FastFlavor<number, "EvmBlockNumber">;
+export type NtpBlockNumber = FastFlavor<number, "NtpBlockNumber">;
+export type MidnightBlockNumber = FastFlavor<number, "MidnightBlockNumber">;
+export type CardanoBlockNumber = FastFlavor<number, "CardanoBlockNumber">;
+export type BitcoinBlockNumber = FastFlavor<number, "BitcoinBlockNumber">;
+
+export type BlockNumber =
+  | EffectstreamBlockNumber
+  | EvmBlockNumber
+  | NtpBlockNumber
+  | MidnightBlockNumber
+  | CardanoBlockNumber
+  | BitcoinBlockNumber;
+
+/**
+ * recall: slots may be empty, so absolute slot number is not usually equal to block number
+ */
+export type AbsoluteSlotNumber = FastFlavor<number, "AbsoluteSlotNumber">;
+export type RelativeSlotNumber = FastFlavor<number, "RelativeSlotNumber">;
+export type EpochNumber = FastFlavor<number, "EpochNumber">;
+
+// don't make it a flavor so it can easily be assigned to/from flavors
+export type HexString0x = `0x${string}`;
+export type HexStringNo0x = FastFlavor<string, "HexStringNo0x">;
+export type Base64String = FastFlavor<string, "Base64String">;
+
+// TODO: change these to brands later
+export type IntervalMs = FastFlavor<number, "IntervalMs">;
+export type IntervalSec = FastFlavor<number, "IntervalSec">;
+export type TimestampMs = FastFlavor<number, "TimestampMs">;
+export type TimestampMsStr = FastFlavor<string, "TimestampMsStr">;
+export type TimestampSec = FastFlavor<number, "TimestampSec">;
+export type TimestampIso8601 = FastFlavor<string, "TimestampIso8601">;
+
+export type AlgorandBlockHash = FastFlavor<UnknownFormat, "AlgorandBlockHash">;
+export type AlgorandTxHash = FastFlavor<UnknownFormat, "AlgorandTxHash">;
+// TODO: this is close to /^[A-Z2-7]{58}$/
+export type AlgorandAddress = FastFlavor<string, "AlgorandAddress">;
+
+export type AvailBlockHash = FastFlavor<UnknownFormat, "AvailBlockHash">;
+export type AvailTxHash = FastFlavor<UnknownFormat, "AvailTxHash">;
+export type AvailAddress = SubstrateAddress;
+
+export type CardanoBlockHash = FastFlavor<string, "CardanoBlockHash">;
+export type CardanoTxHash = FastFlavor<string, "CardanoTxHash">;
+// TODO: bech32 string
+export type CardanoAddress = FastFlavor<string, "CardanoAddress">;
+export type CardanoCredential = FastFlavor<string, "CardanoCredential">;
+export type CardanoPolicyId = FastFlavor<string, "CardanoPolicyId">;
+export type CardanoAssetName = FastFlavor<string, "CardanoAssetName">;
+export type CardanoCip14Fingerprint = FastFlavor<
+  string,
+  "CardanoCip14Fingerprint"
+>;
+export type CardanoPoolId = FastFlavor<string, "CardanoPoolId">;
+export type CardanoAmountLovelace = FastFlavor<string, "CardanoAmountLovelace">;
+
+export type NtpBlockHash = FastFlavor<string, "NtpBlockHash">;
+export type NtpTxHash = FastFlavor<string, "NtpTxHash">; // TODO: is this needed?
+export type NtpAddress = FastFlavor<string, "NtpAddress">; // TODO: is this needed?
+
+export type EvmBlockHash = FastFlavor<HexString0x, "EvmBlockHash">;
+export type EvmTxHash = FastFlavor<HexString0x, "EvmTxHash">;
+export type EvmAddress = FastFlavor<HexString0x, "EvmAddress">;
+export type EvmSelector = FastFlavor<HexString0x, "EvmSelector">;
+export type Evm4ByteSelector = FastFlavor<HexString0x, "Evm4ByteSelector">;
+
+export type MidnightBlockHash = FastFlavor<HexString0x, "MidnightBlockHash">;
+export type MidnightTxHash = FastFlavor<HexString0x, "MidnightTxHash">;
+export type MidnightAddress = FastFlavor<string, "MidnightAddress">;
+export type MidnightSignature = FastFlavor<string, "MidnightSignature">;
+
+export type MinaBlockHash = FastFlavor<UnknownFormat, "MinaBlockHash">;
+export type MinaTxHash = FastFlavor<UnknownFormat, "MinaTxHash">;
+export type MinaAddress = FastFlavor<string, "MinaAddress">;
+
+export type PolkadotAddress = SubstrateAddress;
+export type PolkadotBlockHash = FastFlavor<UnknownFormat, "PolkadotBlockHash">;
+export type PolkadotTxHash = FastFlavor<UnknownFormat, "PolkadotTxHash">;
+
+// TODO: close to the regex /^[1-9A-HJ-NP-Za-km-z]{47,48}$/
+export type SubstrateAddress = FastFlavor<string, "SubstrateAddress">;
+
+export type NearAddress = FastFlavor<string, "NearAddress">;
+
+export type BitcoinBlockHash = FastFlavor<string, "BitcoinBlockHash">;
+export type BitcoinTxId = FastFlavor<string, "BitcoinTxId">;
+export type BitcoinAddress = FastFlavor<string, "BitcoinAddress">;
+
+export type WalletAddress =
+  | AlgorandAddress
+  | AvailAddress
+  | CardanoAddress
+  | EvmAddress
+  | MidnightAddress
+  | MinaAddress
+  | SubstrateAddress
+  | BitcoinAddress;
+
+/**
+ * TODO: probably best to make this more granular to different cryptographic schemes
+ */
+export type EvmPrivateKey = FastFlavor<HexString0x, "EvmPrivateKey">;
+export type GenericPrivateKey = FastFlavor<string, "GenericPrivateKey">;
+export type PrivateKey =
+  | EvmPrivateKey
+  | GenericPrivateKey;
+
+export type EffectstreamTxHash = FastFlavor<HexString0x, "EffectstreamTxHash">;
+export type TxHash =
+  | AlgorandTxHash
+  | AvailTxHash
+  | CardanoTxHash
+  | EvmTxHash
+  | MidnightTxHash
+  | MinaTxHash
+  | EffectstreamTxHash
+  | NtpTxHash;
+// | SubstrateTxHash;
+
+export type EffectstreamBlockHash = FastFlavor<HexString0x, "EffectstreamBlockHash">;
+export type BlockHash =
+  | AlgorandBlockHash
+  | AvailBlockHash
+  | CardanoBlockHash
+  | EvmBlockHash
+  | MidnightBlockHash
+  | MinaBlockHash
+  | EffectstreamBlockHash
+  | NtpBlockHash
+  | BitcoinBlockHash;
+// | SubstrateBlockHash;
+
+export type NtpPageJson = FastFlavor<string, "NTPPageJson">;
+export type EvmRpcPageJson = FastFlavor<string, "EvmRpcPageJson">;
+export type CarpCursorJson = FastFlavor<string, "CarpCursorJson">;
+export type MidnightEncodedStateJson = FastFlavor<
+  string,
+  "MidnightEncodedStateJson"
+>;