pi-crew 0.6.3 → 0.6.4

package/src/utils/guards.ts

@@ -0,0 +1,110 @@
+/**
+ * Centralized type guard library for pi-crew.
+ *
+ * Inspired by @ayulab/runtime-core — all unknown-to-narrowed checks
+ * go through these helpers instead of inline typeof/instanceof.
+ */
+
+// ── Primitive guards ──────────────────────────────────────────────────
+
+/** Narrow `unknown` to `Record<string, unknown>`. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Narrow `unknown` to `string`. */
+export function isString(value: unknown): value is string {
+	return typeof value === "string";
+}
+
+/** Narrow `unknown` to a non-empty string. */
+export function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+/** Narrow `unknown` to `number` (excludes NaN). */
+export function isNumber(value: unknown): value is number {
+	return typeof value === "number" && !Number.isNaN(value);
+}
+
+/** Narrow `unknown` to `boolean`. */
+export function isBoolean(value: unknown): value is boolean {
+	return typeof value === "boolean";
+}
+
+/** Narrow `unknown` to `readonly string[]`. */
+export function isStringArray(value: unknown): value is readonly string[] {
+	return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+/**
+ * Higher-order guard: build a guard that checks every element of an array.
+ *
+ * @example
+ * const isNumberArray = isArrayOf(isNumber);
+ */
+export function isArrayOf<T>(
+	guard: (item: unknown) => item is T,
+): (value: unknown) => value is readonly T[] {
+	return (value: unknown): value is readonly T[] =>
+		Array.isArray(value) && value.every(guard);
+}
+
+// ── Record field extractors ───────────────────────────────────────────
+
+/** Extract a string field from a record, returning `undefined` if absent. */
+export function getStringField(value: unknown, key: string): string | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "string" ? field : undefined;
+}
+
+/** Extract a number field from a record, returning `undefined` if absent. */
+export function getNumberField(value: unknown, key: string): number | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "number" && !Number.isNaN(field) ? field : undefined;
+}
+
+/** Extract a boolean field from a record, returning `undefined` if absent. */
+export function getBooleanField(value: unknown, key: string): boolean | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "boolean" ? field : undefined;
+}
+
+/** Extract a nested record field from a record, returning `undefined` if absent. */
+export function getRecordField(value: unknown, key: string): Record<string, unknown> | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return isRecord(field) ? field : undefined;
+}
+
+/** Extract an array field from a record, returning `undefined` if absent. */
+export function getArrayField(value: unknown, key: string): unknown[] | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return Array.isArray(field) ? field : undefined;
+}
+
+// ── Error helpers ─────────────────────────────────────────────────────
+
+/**
+ * Extract a human-readable message from an unknown error value.
+ *
+ * Prefer this over manual `instanceof Error` checks to keep error
+ * handling uniform across the codebase.
+ */
+export function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+// ── Utility types ─────────────────────────────────────────────────────
+
+/** A non-empty readonly array type. */
+export type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
+
+/** Narrow a readonly array to a non-empty readonly array. */
+export function hasItems<T>(items: readonly T[]): items is NonEmptyReadonlyArray<T> {
+	return items.length > 0;
+}