@carecard/validate 3.1.25 → 3.1.27

package/index.d.ts

@@ -1,14 +1,27 @@
+/**
+ * Runtime-compatible TypeScript declarations for the CommonJS
+ * `@carecard/validate` package.
+ */
+
+export type ValidatePropertiesInput = Record<string, unknown> | null | undefined;
+export type ValidatePropertiesResult = Record<string, unknown>;
+export type BoolValidator = (input: unknown) => boolean;
+export type FailureMessageValidator = (input: unknown) => string | null;
+export type InStringArrayValidator = (stringArray: readonly string[], input: unknown) => boolean;
+
 /**
  * Utility function to validate multiple properties of an object at once.
  */
-export function validateProperties(obj?: Record<string, any>): Record<string, any>;
+export function validateProperties(obj?: ValidatePropertiesInput): ValidatePropertiesResult;
+
+export type ValidateWhitelistFlattenKeyStyle = 'path' | 'leaf';
 
 /**
  * Options for {@link validateWhitelistProperties}.
  */
 export interface ValidateWhitelistPropertiesOptions {
     /** Properties allowed in the input but not required. */
-    optionalProperties?: string[];
+    optionalProperties?: readonly string[] | null;
     /** When true, the returned object's keys are converted to snake_case. */
     convertToSnakeCase?: boolean;
     /**
@@ -24,46 +37,74 @@ export interface ValidateWhitelistPropertiesOptions {
      *
      * Defaults to `path`.
      */
-    flattenKeyStyle?: 'path' | 'leaf';
+    flattenKeyStyle?: ValidateWhitelistFlattenKeyStyle;
 }
 
-/**
- * Validates and transforms whitelisted properties from an input object.
- *
- * - Supports nested objects via dot-notation paths (e.g. `"address.city"`),
- *   up to 5 levels deep. The function checks that each path resolves to an
- *   existing leaf property and validates the leaf value by its leaf segment.
- * - Extracts only the whitelisted (required + optional) leaf properties and
- *   rebuilds the same nested shape in the result.
- * - Validates values via {@link validateProperties}.
- * - Throws a "Bad_Input" error when any required property is missing/invalid,
- *   when a provided optional property has an invalid value, when a path
- *   exceeds 5 levels of nesting, or when the combined count of
- *   `requiredProperties` and `options.optionalProperties` exceeds 5000.
- * - Array values are supported: if a leaf value is an array, the per-leaf
- *   validator is applied to each element. The leaf is accepted only when every
- *   element passes validation, and the returned value is an array of the
- *   validated elements (e.g. `{ name: ["First", "Other"] }` is validated like
- *   `{ name: "First" }` and `{ name: "Other" }` individually).
- * - Optionally converts the resulting keys (including nested keys) to snake_case.
- * - Optionally flattens the result after snake_case conversion.
- *
- * @param inputObject The input object (e.g. `req.body` or `req.params`).
- * @param requiredProperties Leaf paths that must be present and valid. Dot-notation supported.
- * @param options Optional additional leaf paths plus output transformation flags.
- */
-export function validateWhitelistProperties(
-    inputObject: Record<string, any>,
-    requiredProperties?: string[],
-    options?: ValidateWhitelistPropertiesOptions,
-): Promise<Record<string, any>>;
+export interface ValidateWhitelistPropertiesFunction {
+    /**
+     * Validates and transforms whitelisted properties from an input object.
+     *
+     * - Supports nested objects via dot-notation paths (e.g. `"address.city"`),
+     *   up to 5 levels deep. The function checks that each path resolves to an
+     *   existing leaf property and validates the leaf value by its leaf segment.
+     * - Extracts only the whitelisted (required + optional) leaf properties and
+     *   rebuilds the same nested shape in the result.
+     * - Validates values via {@link validateProperties}.
+     * - Throws a "Bad_Input" error when any required property is missing/invalid,
+     *   when a provided optional property has an invalid value, when a path
+     *   exceeds 5 levels of nesting, or when the combined count of
+     *   `requiredProperties` and `options.optionalProperties` exceeds 5000.
+     * - Array values are supported: if a leaf value is an array, the per-leaf
+     *   validator is applied to each element. The leaf is accepted only when every
+     *   element passes validation, and the returned value is an array of the
+     *   validated elements.
+     * - Optionally converts the resulting keys, including nested keys, to snake_case.
+     * - Optionally flattens the result after snake_case conversion.
+     *
+     * @param inputObject The input object, for example `req.body` or `req.params`.
+     * @param requiredProperties Leaf paths that must be present and valid. Dot notation is supported.
+     * @param options Optional additional leaf paths plus output transformation flags.
+     */
+    (
+        inputObject?: ValidatePropertiesInput,
+        requiredProperties?: readonly string[] | null,
+        options?: ValidateWhitelistPropertiesOptions | null,
+    ): Promise<ValidatePropertiesResult>;
+    validateWhitelistProperties: ValidateWhitelistPropertiesFunction;
+    MAX_NESTING_DEPTH: 5;
+    MAX_KEYS_PER_CALL: 5000;
+}
+
+export const validateWhitelistProperties: ValidateWhitelistPropertiesFunction;
+
+export type UserRoleRequestRole = 'student' | 'intern' | 'volunteer';
+export type UserRoleRequestScopeRequirement = boolean | typeof REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT;
 
 export const DEFAULT_USER_ROLE_REQUEST_ROLE: 'student';
 export const REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT: 'whenRoleOrScopePresent';
 
 export interface ValidateNewUserRoleRequestOptions {
-    defaultRole?: 'student' | undefined;
-    requireScope?: boolean | typeof REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT;
+    defaultRole?: UserRoleRequestRole | undefined;
+    requireScope?: UserRoleRequestScopeRequirement;
+}
+
+export interface ValidateNewUserRoleRequestInput extends Record<string, unknown> {
+    role_name?: unknown;
+    roleName?: unknown;
+    role?: unknown;
+    institution_id?: unknown;
+    institutionId?: unknown;
+    campus_id?: unknown;
+    campusId?: unknown;
+    program_id?: unknown;
+    programId?: unknown;
+}
+
+export interface ValidateNewUserRoleRequestPayload extends Record<string, unknown> {
+    role_name?: string;
+    institution_id?: string;
+    campus_id?: string;
+    program_id?: string;
 }
 
 /**
@@ -72,79 +113,78 @@ export interface ValidateNewUserRoleRequestOptions {
  * both institution_id and campus_id must be provided.
  */
 export function validateNewUserRoleRequestObject(
-    roleRequest?: Record<string, any>,
-    options?: ValidateNewUserRoleRequestOptions,
-): Record<string, any>;
+    roleRequest?: ValidateNewUserRoleRequestInput | null,
+    options?: ValidateNewUserRoleRequestOptions | null,
+): ValidateNewUserRoleRequestPayload;
 
 /** Checks if the string is a valid image URL format. */
-export function isImageUrl(imageUrl: any): boolean;
+export const isImageUrl: BoolValidator;
 /** Checks if the value is an integer. */
-export function isInteger(number: any): boolean;
+export const isInteger: BoolValidator;
 /** Checks if the string is a valid JSON string and can be parsed into an object. */
-export function isValidJsonString(str: any): boolean;
+export const isValidJsonString: BoolValidator;
 /** Checks if the string represents a valid integer. */
-export function isValidIntegerString(str: any): boolean;
+export const isValidIntegerString: BoolValidator;
 /** Checks if the string is a valid UUID. */
-export function isValidUuidString(str: any): boolean;
+export const isValidUuidString: BoolValidator;
 /** Checks if the string contains only alphanumeric characters, spaces, underscores, or hyphens. */
-export function isCharactersString(str: any): boolean;
+export const isCharactersString: BoolValidator;
 /** Checks if the string is a valid street address format. */
-export function isStreetString(str: any): boolean;
+export const isStreetString: BoolValidator;
 /** Checks if the string is a valid name format. */
-export function isNameString(str: any): boolean;
+export const isNameString: BoolValidator;
 /** Checks if the string is safe for search queries. */
-export function isSafeSearchString(str: any): boolean;
+export const isSafeSearchString: BoolValidator;
 /** Checks if the string is a valid email address. */
-export function isEmailString(email: any): boolean;
+export const isEmailString: BoolValidator;
 /** Checks if the string is a valid JWT format. */
-export function isJwtString(jwt: any): boolean;
+export const isJwtString: BoolValidator;
 /** Checks if the string is a valid strong password. */
-export function isPasswordString(password: any): boolean;
+export const isPasswordString: BoolValidator;
 /** Checks if the string is a valid simple password. */
-export function isSimplePasswordString(password: any): boolean;
+export const isSimplePasswordString: BoolValidator;
 /** Returns a failure message if the password is not strong enough. */
-export function isPasswordStringFailureMessage(password: any): string | null;
+export const isPasswordStringFailureMessage: FailureMessageValidator;
 /** Returns a failure message if the password is not valid as a simple password. */
-export function isSimplePasswordStringFailureMessage(password: any): string | null;
+export const isSimplePasswordStringFailureMessage: FailureMessageValidator;
 /** Checks if the string is a valid username. */
-export function isUsernameString(str: any): boolean;
+export const isUsernameString: BoolValidator;
 /** Checks if the string is a valid phone number. */
-export function isPhoneNumber(str: any): boolean;
+export const isPhoneNumber: BoolValidator;
 /** Checks if the string is URL-safe. */
-export function isUrlSafeString(inputString: any): boolean;
+export const isUrlSafeString: BoolValidator;
 /** Checks if the string length is between 6 and 24 characters. */
-export function isString6To24CharacterLong(password: any): boolean;
+export const isString6To24CharacterLong: BoolValidator;
 /** Checks if the string length is between 6 and 16 characters. */
-export function isString6To16CharacterLong(password: any): boolean;
+export const isString6To16CharacterLong: BoolValidator;
 /** Checks if the string is a valid Canadian province abbreviation (ON, QC). */
-export function isProvinceString(inputString: any): boolean;
+export const isProvinceString: BoolValidator;
 /** Checks if the value is a boolean. */
-export function isBoolValue(inputValue: any): boolean;
+export const isBoolValue: BoolValidator;
 /** Checks if the string is a valid Canadian postal code. */
-export function isPostalCodeString(inputString: any): boolean;
+export const isPostalCodeString: BoolValidator;
 /** Checks if the string contains only allowed "safe" characters. */
-export function isSafeString(str: any): boolean;
+export const isSafeString: BoolValidator;
 /** Checks if the value is non-empty text up to the supported maximum length. */
-export function isTextString(str: any): boolean;
-/** Checks if a string exists within a given array of strings (case-insensitive). */
-export function isInStringArray(StringArray: string[], inputString: any): boolean;
+export const isTextString: BoolValidator;
+/** Checks if a string exists within a given array of strings, case-insensitive. */
+export const isInStringArray: InStringArrayValidator;
 /** Checks if the string is one of the supported user role request statuses. */
-export function isUserRoleRequestStatusString(inputString: any): boolean;
+export const isUserRoleRequestStatusString: BoolValidator;
 /** Checks if the string is a supported new user role request role. */
-export function isUserRoleRequestRoleString(inputString: any): boolean;
-/** Checks if the string is a valid country code (e.g., +1). */
-export function isCountryCodeString(str: any): boolean;
+export const isUserRoleRequestRoleString: BoolValidator;
+/** Checks if the string is a valid country code, for example +1. */
+export const isCountryCodeString: BoolValidator;
 /** Checks if the string is a valid domain name. */
-export function isValidDomainName(domain: any): boolean;
+export const isValidDomainName: BoolValidator;
 /** Checks if the string is a valid ISO 8601 timestamp with time zone. */
-export function isValidTimestampzString(str: any): boolean;
+export const isValidTimestampzString: BoolValidator;
 /** Checks if the string is a valid ISO 8601 timestamp without time zone. */
-export function isValidTimestampString(str: any): boolean;
-
+export const isValidTimestampString: BoolValidator;
 /** Checks if the string is a valid URL. */
-export function isValidUrl(url: any): boolean;
+export const isValidUrl: BoolValidator;
 /** Checks if the array contains only safe strings. */
-export function isValidArrayOfStrings(arr: any): boolean;
+export const isValidArrayOfStrings: BoolValidator;
 
 /**
  * Utility functions for validating various types of strings and values.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@carecard/validate",
-    "version": "3.1.25",
+    "version": "3.1.27",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/CareCard-ca/pkg-validate.git"

package/readme.md

@@ -121,7 +121,7 @@ where the package supports both.
 
 `validateWhitelistProperties` extracts only the required and optional property
 paths you provide, validates each leaf through `validateProperties`, and returns
-a `Promise<Record<string, any>>` with the sanitized output.
+a `Promise<ValidatePropertiesResult>` with the sanitized output.
 
 ```js
 const body = {
@@ -333,10 +333,11 @@ await validateWhitelistProperties(input, ['name', 'user.name', 'user.email'], {
 The package ships `index.d.ts` and declares types for the CommonJS exports.
 
 ```ts
-import { validateWhitelistProperties, isEmailString } from '@carecard/validate';
+import { validateWhitelistProperties, isEmailString, ValidatePropertiesResult } from '@carecard/validate';
 
 const valid: boolean = isEmailString('jane@example.com');
-const output: Record<string, any> = await validateWhitelistProperties({ first_name: 'Jane' }, ['first_name']);
+const output: ValidatePropertiesResult = await validateWhitelistProperties({ first_name: 'Jane' }, ['first_name']);
+const maxDepth: 5 = validateWhitelistProperties.MAX_NESTING_DEPTH;
 ```
 
 ## Project Layout