@spudlabs/guardis 0.4.0

package/esm/src/guard.d.ts

@@ -0,0 +1,288 @@
+/**
+ * guard.ts
+ * @module
+ */
+import type { InferShape, JsonObject, JsonPrimitive, JsonValue, Parser, ParserEntry, TupleOfLength, TypeGuard, TypeGuardShape } from "./types.js";
+/**
+ * Creates a type guard from a parser function.
+ *
+ * The parser should perform whatever checks are necessary to safely establish
+ * that the input is of the specified type.
+ *
+ * Injects the `has` utility method as the second argument of any parser, as
+ * a convenience to check if a property exists in an object.
+ *
+ * @param parser A function that returns the value if valid, or null if invalid.
+ * @returns A type guard function with utility methods.
+ *
+ * @example
+ * ```typescript
+ * const parseString = (val: unknown): string | null => typeof val === 'string' ? val : null;
+ * const isString = createTypeGuard(parseString);
+ * ```
+ */
+export declare function createTypeGuard<T1>(parser: Parser<T1>): TypeGuard<T1>;
+/**
+ * Creates a type guard from a parser function with a custom type name.
+ *
+ * The name is used for error messages when the type guard fails.
+ *
+ * @param name The type name to use for error messages.
+ * @param parser A function that returns the value if valid, or null if invalid.
+ * @returns A type guard function with utility methods.
+ *
+ * @example
+ * ```typescript
+ * const isPositive = createTypeGuard("positive number", (val: unknown): number | null =>
+ *   typeof val === 'number' && val > 0 ? val : null
+ * );
+ * ```
+ */
+export declare function createTypeGuard<T1>(name: string, parser: Parser<T1>): TypeGuard<T1>;
+/**
+ * Creates a type guard from a shape object.
+ *
+ * The shape maps property names to guard predicates or nested shapes.
+ * The resulting type guard validates that an object matches the shape.
+ *
+ * @param shape A shape object mapping keys to guards or nested shapes.
+ * @returns A type guard function with utility methods.
+ *
+ * @example
+ * ```typescript
+ * const isUser = createTypeGuard({ name: isString, age: isNumber });
+ * ```
+ */
+export declare function createTypeGuard<S extends TypeGuardShape>(shape: S): TypeGuard<InferShape<S>>;
+/**
+ * Creates a type guard from a shape object with a custom type name.
+ *
+ * @param name The type name to use for error messages.
+ * @param shape A shape object mapping keys to guards or nested shapes.
+ * @returns A type guard function with utility methods.
+ */
+export declare function createTypeGuard<S extends TypeGuardShape>(name: string, shape: S): TypeGuard<InferShape<S>>;
+/**
+ * Converts a ParserEntry (parser function, named parser object, or shape) into a TypeGuard.
+ * Shared by `batch` and `extend` to avoid duplicating entry detection logic.
+ */
+export declare function entryToGuard(entry: ParserEntry): TypeGuard<unknown>;
+/**
+ * Returns true if input satisfies type boolean.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isBoolean: TypeGuard<boolean>;
+/**
+ * Returns true if input satisfies type string.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isString: TypeGuard<string>;
+/**
+ * Returns true if input satisfies type number. Returns false if `NaN` is passed.
+ *
+ * While `NaN` is technically a number in JavaScript, it is not a valid value for many applications
+ * and will fail if used with common numeric operations.
+ *
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isNumber: TypeGuard<number>;
+/**
+ * Returns true if input satisfies type symbol.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isSymbol: TypeGuard<symbol>;
+/**
+ * Returns true if input satisfies type binary.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isBinary: TypeGuard<0 | 1>;
+/**
+ * Returns true if input satisfies type numeric.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isNumeric: TypeGuard<number>;
+/**
+ * Returns true if input satisfies type Function.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isFunction: TypeGuard<(...args: unknown[]) => unknown>;
+/**
+ * Returns true if input satisfies type undefined.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isUndefined: TypeGuard<undefined>;
+/**
+ * Returns true if input satisfies type null.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+declare const isNull: TypeGuard<null>;
+/**
+ * Returns true if input is a JSON-able primitive date type
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isJsonPrimitive: TypeGuard<JsonPrimitive>;
+/**
+ * Returns true if input satisfies type object. _BEWARE_ object
+ * can apply to many different types, including arrays. This
+ * is not as type safe as you might think.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isObject: TypeGuard<object>;
+/** Returns true if input satisfies type PropertyKey.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isPropertyKey: TypeGuard<PropertyKey>;
+/**
+ * Returns true if input satisfies type object. _BEWARE_ object
+ * can apply to many different types, including arrays. This
+ * is not as type safe as you might think.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isJsonObject: TypeGuard<JsonObject>;
+/**
+ * Returns true if input satisfies type array.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isArray: TypeGuard<unknown[]> & {
+    /**
+     * Returns true if input satisfies type array of T.
+     * @param guard The type guard for the array elements
+     * @returns {boolean}
+     */
+    of: <T>(guard: TypeGuard<T>) => TypeGuard<T[]>;
+};
+/**
+ * Returns true if input satisfies type array.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+export declare const isJsonArray: TypeGuard<JsonValue[] | readonly JsonValue[]>;
+/**
+ * Checks if a given value is a valid JSON value.
+ *
+ * This type guard leverages helper functions to determine if the provided value is a valid JSON
+ * primitive, JSON array, or JSON object. If the value satisfies any of these conditions, it is
+ * considered a valid JSON value.
+ *
+ * @param t - The value to be checked.
+ * @returns The value itself if it is a valid JSON value; otherwise, returns null.
+ *
+ * @remarks
+ * - For primitive types, arrays, and objects, the guard confirms conformance with the JSON value standards.
+ *
+ * @example
+ * const value: unknown = getValue();
+ * const jsonValue = isJsonValue(value);
+ * if (jsonValue !== null) {
+ *   // Work with the confirmed JSON value.
+ * }
+ */
+export declare const isJsonValue: TypeGuard<JsonValue>;
+/**
+ * A type guard function that checks if a value is a Date object.
+ *
+ * @param t - The value to check
+ * @returns The original Date object if the value is a Date, otherwise null
+ *
+ * @example
+ * ```typescript
+ * const maybeDate: unknown = new Date();
+ *
+ * if (isDate(maybeDate)) {
+ *   // maybeDate is now typed as Date
+ *   console.log(maybeDate.toISOString());
+ * }
+ * ```
+ */
+export declare const isDate: TypeGuard<Date>;
+/**
+ * Returns true if input satisfies type null or undefined.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+declare const isNil: TypeGuard<null | undefined>;
+/**
+ * Returns true if input is undefined, null, empty string, object with length
+ * of 0 or object without enumerable keys.
+ *
+ * Strings are trimmed when evaluated.
+ * @param {unknown} t
+ * @return {boolean}
+ */
+declare const isEmpty: TypeGuard<null | undefined | "" | [] | Record<string, never>>;
+/**
+ * Returns true if the value is iterable (has Symbol.iterator). Does not
+ * check the type contained within the iterable.
+ * @param t
+ * @returns
+ */
+declare const isIterable: TypeGuard<Iterable<unknown>>;
+/**
+ * Type guard that checks if a value is a tuple (array) of a specific length.
+ *
+ * A tuple is an array with a fixed number of elements. This function validates
+ * that the input is an array and has exactly the specified length.
+ *
+ * @typeParam N - The expected length of the tuple
+ * @param t - The value to check
+ * @param length - The expected length of the tuple
+ * @returns Type predicate indicating if the value is a tuple of length N
+ *
+ * @example
+ * ```typescript
+ * const value: unknown = [1, 2, 3];
+ *
+ * if (isTuple(value, 3)) {
+ *   // value is now typed as [unknown, unknown, unknown]
+ *   console.log(value.length); // 3
+ * }
+ *
+ * // Check for empty tuple
+ * if (isTuple([], 0)) {
+ *   console.log("Empty tuple");
+ * }
+ * ```
+ */
+declare const isTuple: {
+    <N extends number>(t: unknown, length: N): t is TupleOfLength<N>;
+    strict<N extends number>(t: unknown, length: N, errorMsg?: string): t is TupleOfLength<N>;
+    /**
+     * Assertion function that throws an error if the value is not a tuple of the specified length.
+     * TypeScript will narrow the type to TupleOfLength<N> after this assertion.
+     * @typeParam N - The expected length of the tuple
+     * @param t - The value to check
+     * @param length - The expected length of the tuple
+     * @param errorMsg - Optional custom error message
+     * @throws {TypeError} If the value is not a tuple of the specified length
+     */
+    assert: <N extends number>(t: unknown, length: N, errorMsg?: string) => asserts t is TupleOfLength<N>;
+    or<N extends number, T2>(length: N, guard: TypeGuard<T2>): TypeGuard<TupleOfLength<N> | T2>;
+    /**
+     * Optional variant of isTuple that accepts undefined or a tuple of the specified length.
+     * @typeParam N - The expected length of the tuple
+     * @param t - The value to check
+     * @param length - The expected length of the tuple
+     * @returns true if the value is undefined or a tuple of the specified length, otherwise false
+     */
+    optional: {
+        <N extends number>(t: unknown, length: N): t is TupleOfLength<N> | undefined;
+        strict<N extends number>(t: unknown, length: N, errorMsg?: string): t is TupleOfLength<N> | undefined;
+        assert: <N extends number>(t: unknown, length: N, errorMsg?: string) => t is TupleOfLength<N> | undefined;
+    };
+};
+export { isEmpty, isIterable, isNil, isNull, isTuple };
+//# sourceMappingURL=guard.d.ts.map

package/esm/src/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/src/guard.ts"],"names":[],"mappings":"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"}