@gnwebsoft/ui 3.0.8 → 4.0.0

package/dist/types/index.d.cts

@@ -1,5 +1,7 @@
 import { GridSortModel } from '@mui/x-data-grid';
 export { a as AsyncSelectMultiPayload, A as AsyncSelectPayload } from '../AsyncSelectPayload-B9-6l33R.cjs';
+export { E as EventOrValue, F as FormChangeEvent, c as GenericEventHandler, G as GenericSyntheticEvent, H as HtmlSelectElement, a as InputChangeEvent, I as InputElement, S as SelectChangeEvent, b as TransformInputHandler, T as TransformOutputHandler, g as createEventValueExtractor, f as extractEventValue, e as isFormChangeEvent, i as isInputChangeEvent, d as isSelectChangeEvent } from '../events-BcHVCLBz.cjs';
+import 'react';
 
 /**
  * Type definition for server validation errors structure.
@@ -213,6 +215,591 @@ interface OperationResponse {
     rowsAffected: number;
 }
 
+/**
+ * Type-safe API request and response utilities
+ * @module types/api
+ */
+/**
+ * HTTP methods supported by the API
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * Valid JSON primitive types that can be sent in request bodies
+ */
+type JsonPrimitive = string | number | boolean | null;
+/**
+ * Valid JSON values (primitives, objects, arrays)
+ */
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * JSON object with string keys and JSON values
+ */
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * JSON array containing JSON values
+ */
+type JsonArray = JsonValue[];
+/**
+ * Type-safe request body - must be JSON-serializable
+ */
+type RequestBody = JsonObject | JsonArray | FormData;
+/**
+ * Standard HTTP headers with known header names
+ */
+type HttpHeaders = Record<string, string>;
+/**
+ * Options for making HTTP requests (based on fetch API)
+ */
+interface RequestOptions {
+    /**
+     * HTTP method for the request
+     */
+    method: HttpMethod;
+    /**
+     * Request headers
+     */
+    headers?: HttpHeaders;
+    /**
+     * Request body (string for JSON, FormData for file uploads)
+     */
+    body?: string | FormData;
+    /**
+     * Request credentials mode
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Request mode (cors, no-cors, same-origin)
+     */
+    mode?: RequestMode;
+    /**
+     * Cache mode for the request
+     */
+    cache?: RequestCache;
+    /**
+     * Redirect mode for the request
+     */
+    redirect?: RequestRedirect;
+    /**
+     * Referrer policy for the request
+     */
+    referrerPolicy?: ReferrerPolicy;
+    /**
+     * AbortSignal for request cancellation
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Configuration options for API calls
+ */
+interface ApiCallOptions {
+    /**
+     * Custom headers to include in the request
+     */
+    headers?: HttpHeaders;
+    /**
+     * Whether to include authentication token
+     * @defaultValue true
+     */
+    includeAuth?: boolean;
+    /**
+     * AbortSignal for request cancellation
+     */
+    signal?: AbortSignal;
+    /**
+     * Custom base URL (overrides default)
+     */
+    baseUrl?: string;
+}
+/**
+ * Options for fetch operations with any additional parameters
+ */
+interface FetchOptions extends Omit<RequestInit, 'body' | 'headers'> {
+    /**
+     * Request headers
+     */
+    headers?: HttpHeaders;
+    /**
+     * Request body
+     */
+    body?: RequestBody;
+}
+/**
+ * Type guard to check if a value is a valid JSON object
+ */
+declare function isJsonObject(value: unknown): value is JsonObject;
+/**
+ * Type guard to check if a value is a valid JSON array
+ */
+declare function isJsonArray(value: unknown): value is JsonArray;
+/**
+ * Type guard to check if a value is FormData
+ */
+declare function isFormData(value: unknown): value is FormData;
+/**
+ * Type guard to check if a value is a valid request body
+ */
+declare function isRequestBody(value: unknown): value is RequestBody;
+
+/**
+ * Utility types and type helpers for enhanced type safety
+ *
+ * @packageDocumentation
+ */
+/**
+ * Makes all properties of T required and non-nullable
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id?: string;
+ *   name?: string | null;
+ * }
+ *
+ * type RequiredUser = DeepRequired<User>;
+ * // { id: string; name: string }
+ * ```
+ *
+ * @public
+ */
+type DeepRequired<T> = {
+    [P in keyof T]-?: NonNullable<T[P]>;
+};
+/**
+ * Makes all properties of T optional
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * type PartialUser = DeepPartial<User>;
+ * // { id?: string; name?: string }
+ * ```
+ *
+ * @public
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Makes all properties of T readonly deeply
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   profile: {
+ *     name: string;
+ *   };
+ * }
+ *
+ * type ReadonlyUser = DeepReadonly<User>;
+ * // { readonly id: string; readonly profile: { readonly name: string } }
+ * ```
+ *
+ * @public
+ */
+type DeepReadonly<T> = {
+    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+/**
+ * Extracts keys from T that are not undefined
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name?: string;
+ *   email: string | undefined;
+ * }
+ *
+ * type RequiredKeys = RequiredKeys<User>;
+ * // 'id'
+ * ```
+ *
+ * @public
+ */
+type RequiredKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T];
+/**
+ * Extracts keys from T that can be undefined
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name?: string;
+ *   email: string | undefined;
+ * }
+ *
+ * type OptKeys = OptionalKeys<User>;
+ * // 'name' | 'email'
+ * ```
+ *
+ * @public
+ */
+type OptionalKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? K : never;
+}[keyof T];
+/**
+ * Makes specified keys K of type T required
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id?: string;
+ *   name?: string;
+ *   email?: string;
+ * }
+ *
+ * type UserWithId = RequireKeys<User, 'id' | 'email'>;
+ * // { id: string; name?: string; email: string }
+ * ```
+ *
+ * @public
+ */
+type RequireKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * Makes specified keys K of type T optional
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * type UserUpdate = PartialKeys<User, 'name' | 'email'>;
+ * // { id: string; name?: string; email?: string }
+ * ```
+ *
+ * @public
+ */
+type PartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Excludes keys K from type T
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   password: string;
+ *   email: string;
+ * }
+ *
+ * type PublicUser = ExcludeKeys<User, 'password'>;
+ * // { id: string; email: string }
+ * ```
+ *
+ * @public
+ */
+type ExcludeKeys<T, K extends keyof T> = Omit<T, K>;
+/**
+ * Picks only keys K from type T
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * type UserCredentials = PickKeys<User, 'email'>;
+ * // { email: string }
+ * ```
+ *
+ * @public
+ */
+type PickKeys<T, K extends keyof T> = Pick<T, K>;
+/**
+ * Extracts the value type from an array type
+ *
+ * @example
+ * ```typescript
+ * type StringArray = string[];
+ * type Item = ArrayElement<StringArray>;
+ * // string
+ * ```
+ *
+ * @public
+ */
+type ArrayElement<T> = T extends readonly (infer E)[] ? E : never;
+/**
+ * Extracts the return type of an async function
+ *
+ * @example
+ * ```typescript
+ * async function getUser(): Promise<User> {
+ *   return { id: '1', name: 'John' };
+ * }
+ *
+ * type User = AsyncReturnType<typeof getUser>;
+ * // User
+ * ```
+ *
+ * @public
+ */
+type AsyncReturnType<T extends (...args: readonly unknown[]) => Promise<unknown>> = T extends (...args: readonly unknown[]) => Promise<infer R> ? R : never;
+/**
+ * Makes a type nullable (adds null)
+ *
+ * @example
+ * ```typescript
+ * type Username = string;
+ * type NullableUsername = Nullable<Username>;
+ * // string | null
+ * ```
+ *
+ * @public
+ */
+type Nullable<T> = T | null;
+/**
+ * Makes a type optional (adds undefined)
+ *
+ * @example
+ * ```typescript
+ * type Username = string;
+ * type OptionalUsername = Maybe<Username>;
+ * // string | undefined
+ * ```
+ *
+ * @public
+ */
+type Maybe<T> = T | undefined;
+/**
+ * Makes a type nullish (adds null and undefined)
+ *
+ * @example
+ * ```typescript
+ * type Username = string;
+ * type NullishUsername = Nullish<Username>;
+ * // string | null | undefined
+ * ```
+ *
+ * @public
+ */
+type Nullish<T> = T | null | undefined;
+/**
+ * Creates a union of all possible paths through an object type
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   profile: {
+ *     name: string;
+ *     address: {
+ *       city: string;
+ *     };
+ *   };
+ * }
+ *
+ * type Paths = ObjectPaths<User>;
+ * // 'profile' | 'profile.name' | 'profile.address' | 'profile.address.city'
+ * ```
+ *
+ * @public
+ */
+type ObjectPaths<T> = {
+    [K in keyof T & string]: T[K] extends object ? K | `${K}.${ObjectPaths<T[K]>}` : K;
+}[keyof T & string];
+/**
+ * Merges two types, with properties from B overriding those in A
+ *
+ * @example
+ * ```typescript
+ * interface A {
+ *   id: number;
+ *   name: string;
+ * }
+ *
+ * interface B {
+ *   id: string;
+ *   email: string;
+ * }
+ *
+ * type Merged = Merge<A, B>;
+ * // { id: string; name: string; email: string }
+ * ```
+ *
+ * @public
+ */
+type Merge<A, B> = Omit<A, keyof B> & B;
+/**
+ * Ensures a type is serializable (no functions, symbols, undefined)
+ *
+ * @example
+ * ```typescript
+ * interface Data {
+ *   id: string;
+ *   callback: () => void;
+ *   value: number;
+ * }
+ *
+ * type SerializableData = Serializable<Data>;
+ * // { id: string; value: number }
+ * ```
+ *
+ * @public
+ */
+type Serializable<T> = {
+    [K in keyof T as T[K] extends (...args: readonly unknown[]) => unknown ? never : T[K] extends symbol ? never : T[K] extends undefined ? never : K]: T[K] extends object ? Serializable<T[K]> : T[K];
+};
+/**
+ * Converts a union type to an intersection type
+ *
+ * @example
+ * ```typescript
+ * type Union = { a: string } | { b: number };
+ * type Intersection = UnionToIntersection<Union>;
+ * // { a: string } & { b: number }
+ * ```
+ *
+ * @public
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Gets all keys of T whose values extend V
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   age: number;
+ *   name: string;
+ *   active: boolean;
+ * }
+ *
+ * type StringKeys = KeysOfType<User, string>;
+ * // 'id' | 'name'
+ * ```
+ *
+ * @public
+ */
+type KeysOfType<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];
+/**
+ * Ensures a value is exactly the type T (no wider types allowed)
+ *
+ * @example
+ * ```typescript
+ * const config: Exact<{ debug: boolean }> = {
+ *   debug: true,
+ *   // extra: 'value'  // ❌ Error: extra property not allowed
+ * };
+ * ```
+ *
+ * @public
+ */
+type Exact<T, Shape = T> = T extends Shape ? Exclude<keyof T, keyof Shape> extends never ? T : never : never;
+/**
+ * Creates a branded type for nominal typing
+ * This prevents mixing values of the same primitive type
+ *
+ * @example
+ * ```typescript
+ * type UserId = Brand<string, 'UserId'>;
+ * type ProductId = Brand<string, 'ProductId'>;
+ *
+ * const userId: UserId = '123' as UserId;
+ * const productId: ProductId = '456' as ProductId;
+ *
+ * // ❌ Type error: UserId is not assignable to ProductId
+ * const test: ProductId = userId;
+ * ```
+ *
+ * @public
+ */
+type Brand<T, TBrand extends string> = T & {
+    readonly __brand: TBrand;
+};
+/**
+ * Helper to create a branded value
+ *
+ * @param value - The value to brand
+ * @returns The value as a branded type
+ *
+ * @example
+ * ```typescript
+ * type UserId = Brand<string, 'UserId'>;
+ * const id = brand<string, 'UserId'>('user-123');
+ * // id has type UserId
+ * ```
+ *
+ * @public
+ */
+declare function brand<T, TBrand extends string>(value: T): Brand<T, TBrand>;
+/**
+ * Removes branding from a branded type
+ *
+ * @example
+ * ```typescript
+ * type UserId = Brand<string, 'UserId'>;
+ * type PlainId = Unbrand<UserId>;
+ * // string
+ * ```
+ *
+ * @public
+ */
+type Unbrand<T> = T extends infer U & {
+    readonly __brand: string;
+} ? U : T;
+/**
+ * Type-safe Object.keys that preserves key types
+ *
+ * @param obj - The object to get keys from
+ * @returns Array of keys with proper type
+ *
+ * @example
+ * ```typescript
+ * const user = { id: '1', name: 'John' } as const;
+ * const keys = typedKeys(user);
+ * // keys has type: ('id' | 'name')[]
+ * ```
+ *
+ * @public
+ */
+declare function typedKeys<T extends Record<string, unknown>>(obj: T): Array<keyof T>;
+/**
+ * Type-safe Object.entries that preserves key and value types
+ *
+ * @param obj - The object to get entries from
+ * @returns Array of [key, value] tuples with proper types
+ *
+ * @example
+ * ```typescript
+ * const user = { id: '1', age: 30 } as const;
+ * const entries = typedEntries(user);
+ * // entries has type: ['id', '1'] | ['age', 30]
+ * ```
+ *
+ * @public
+ */
+declare function typedEntries<T extends Record<string, unknown>>(obj: T): Array<[keyof T, T[keyof T]]>;
+/**
+ * Type-safe Object.values that preserves value types
+ *
+ * @param obj - The object to get values from
+ * @returns Array of values with proper type
+ *
+ * @example
+ * ```typescript
+ * const user = { id: '1', age: 30 };
+ * const values = typedValues(user);
+ * // values has type: (string | number)[]
+ * ```
+ *
+ * @public
+ */
+declare function typedValues<T extends Record<string, unknown>>(obj: T): Array<T[keyof T]>;
+
 interface PostModel<TFilterModel> {
     filterModel?: TFilterModel;
     pageOffset: number;
@@ -230,4 +817,4 @@ interface ValueLabel {
     Label: string;
 }
 
-export type { ApiResponse, AsyncMultiSelectPayload, ListResponse, OperationResponse, OptionItem, OptionItem2, PostModel, ValidationErrors, ValueLabel };
+export { type ApiCallOptions, type ApiResponse, type ArrayElement, type AsyncMultiSelectPayload, type AsyncReturnType, type Brand, type DeepPartial, type DeepReadonly, type DeepRequired, type Exact, type ExcludeKeys, type FetchOptions, type HttpHeaders, type HttpMethod, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, type KeysOfType, type ListResponse, type Maybe, type Merge, type Nullable, type Nullish, type ObjectPaths, type OperationResponse, type OptionItem, type OptionItem2, type OptionalKeys, type PartialKeys, type PickKeys, type PostModel, type RequestBody, type RequestOptions, type RequireKeys, type RequiredKeys, type Serializable, type Unbrand, type UnionToIntersection, type ValidationErrors, type ValueLabel, brand, isFormData, isJsonArray, isJsonObject, isRequestBody, typedEntries, typedKeys, typedValues };