@carecard/validate 3.1.25 → 3.1.26

package/.husky/pre-commit

@@ -1,5 +1,3 @@
-npm run lint:fix
-npm run format
-
 # Run tests
-npm run test:All
+npm run test
+npm run test:types

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/lib/validateWhitelistProperties.js

@@ -16,8 +16,6 @@ const MAX_NESTING_DEPTH = 5;
  * adversarial inputs.
  */
 const MAX_KEYS_PER_CALL = 5000;
-const DEFAULT_FLATTEN_KEY_STYLE = 'path';
-const VALID_FLATTEN_KEY_STYLES = new Set(['path', 'leaf']);
 
 /**
  * Returns true if the segment contains a mix of snake_case (underscore) and
@@ -163,35 +161,6 @@ function flattenObject(obj, prefix = '', out = {}) {
     return out;
 }
 
-/**
- * Recursively flattens a nested plain object using only each leaf property
- * name as the output key.
- *
- * Example: `{ a: { b: { c: 1, d: 2 } } }` => `{ c: 1, d: 2 }`.
- * If duplicate leaf keys exist at different nesting levels, the higher-level
- * leaf wins. If duplicate leaf keys exist at the same depth, the first
- * traversal wins.
- *
- * @param {Object} obj
- * @param {Object} [out]
- * @param {Object} [depthByKey]
- * @param {number} [depth]
- * @returns {Object}
- */
-function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
-    for (const [key, value] of Object.entries(obj)) {
-        if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
-            flattenObjectByLeafKey(value, out, depthByKey, depth + 1);
-        } else {
-            if (!Object.prototype.hasOwnProperty.call(out, key) || depth < depthByKey[key]) {
-                out[key] = value;
-                depthByKey[key] = depth;
-            }
-        }
-    }
-    return out;
-}
-
 /**
  * Validates and transforms whitelisted properties from an input object.
  *
@@ -212,11 +181,8 @@ function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
  * element passes validation, and the returned value is an array of the
  * validated elements (in the same order).
  *  5. Optionally converts all keys (including nested) to snake_case.
- *  6. Optionally flattens the result (`flattenOutput`). Flattened keys use
- *     full dot paths by default (`flattenKeyStyle: 'path'`) or direct leaf
- *     names when requested (`flattenKeyStyle: 'leaf'`). For duplicate leaf
- *     keys in leaf mode, the shallower value wins; ties keep the first value
- *     encountered. Applied after snake_case conversion.
+ *  6. Optionally flattens the result so every leaf is a top-level key,
+ *     joined by `.` (`flattenOutput`). Applied after snake_case conversion.
  *
  * @param {Object} inputObject - The input object (e.g., req.body / req.params).
  * @param {Array<string>} [requiredProperties=[]] - Leaf paths that MUST be present and valid.
@@ -224,26 +190,17 @@ function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
  * @param {Array<string>} [options.optionalProperties=[]] - Leaf paths allowed but not required.
  * @param {boolean} [options.convertToSnakeCase=false] - Whether to convert keys to snake_case.
  * @param {boolean} [options.flattenOutput=false] - Whether to flatten the result so that
- *   every leaf is a top-level key, with no nested objects in the output.
- * @param {'path'|'leaf'} [options.flattenKeyStyle='path'] - Flattened key naming strategy
- *   when `flattenOutput` is true. `path` uses dot-joined paths; `leaf` uses leaf names.
+ *   every leaf is a top-level key (joined by `.`), with no nested objects in the output.
  * @returns {Promise<Object>} Resolves with the validated (and possibly transformed) object.
  */
 function validateWhitelistProperties(
     inputObject,
     requiredProperties = [],
-    options = { optionalProperties: [], convertToSnakeCase: false, flattenOutput: false, flattenKeyStyle: DEFAULT_FLATTEN_KEY_STYLE },
+    options = { optionalProperties: [], convertToSnakeCase: false, flattenOutput: false },
 ) {
     const optionalProperties = (options && options.optionalProperties) || [];
     const convertToSnakeCase = !!(options && options.convertToSnakeCase);
     const flattenOutput = !!(options && options.flattenOutput);
-    const flattenKeyStyle = options && options.flattenKeyStyle !== undefined ? options.flattenKeyStyle : DEFAULT_FLATTEN_KEY_STYLE;
-
-    if (!VALID_FLATTEN_KEY_STYLES.has(flattenKeyStyle)) {
-        throwBadInputError({
-            userMessage: `Invalid flattenKeyStyle: ${String(flattenKeyStyle)}. Expected "path" or "leaf"`,
-        });
-    }
 
     // Cap the total number of paths to validate per call.
     const totalKeys = (requiredProperties ? requiredProperties.length : 0) + optionalProperties.length;
@@ -314,9 +271,9 @@ function validateWhitelistProperties(
         validatedObject = keysToSnakeCase(validatedObject);
     }
 
-    // 6. Optional flattening.
+    // 6. Optional flattening: produce a flat object with dot-joined keys.
     if (flattenOutput) {
-        validatedObject = flattenKeyStyle === 'leaf' ? flattenObjectByLeafKey(validatedObject) : flattenObject(validatedObject);
+        validatedObject = flattenObject(validatedObject);
     }
 
     return Promise.resolve(validatedObject);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@carecard/validate",
-    "version": "3.1.25",
+    "version": "3.1.26",
     "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