ts-prorm-orm 1.1.0 → 1.2.0

package/dist/user-management.d.ts

@@ -0,0 +1,141 @@
+/**
+ * User and privilege management for the TypeScript ORM.
+ * Supported dialects: MySQL, MariaDB (MySQL 8+ roles also supported).
+ * SQLite throws DatabaseError – user management is not a concept in SQLite.
+ */
+export type PrivilegeType = 'ALL' | 'ALL PRIVILEGES' | 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'CREATE' | 'DROP' | 'INDEX' | 'ALTER' | 'CREATE TEMPORARY TABLES' | 'LOCK TABLES' | 'EXECUTE' | 'CREATE VIEW' | 'SHOW VIEW' | 'CREATE ROUTINE' | 'ALTER ROUTINE' | 'EVENT' | 'TRIGGER' | 'REFERENCES' | 'USAGE' | 'GRANT OPTION' | 'CONNECT' | 'TEMPORARY' | 'CREATEROLE' | 'CREATEDB' | 'SUPERUSER' | 'REPLICATION' | 'BYPASSRLS';
+export type PrivilegeScope = {
+    level: 'global';
+} | {
+    level: 'database';
+    database: string;
+} | {
+    level: 'table';
+    database?: string;
+    table: string;
+} | {
+    level: 'column';
+    database?: string;
+    table: string;
+    columns: string[];
+} | {
+    level: 'routine';
+    database?: string;
+    routine: string;
+    routineType?: 'FUNCTION' | 'PROCEDURE';
+};
+export interface CreateUserOptions {
+    host?: string;
+    password?: string;
+    passwordHash?: string;
+    authPlugin?: string;
+    requireSSL?: boolean;
+    maxConnections?: number;
+    maxQueriesPerHour?: number;
+    maxUpdatesPerHour?: number;
+    maxConnectionsPerHour?: number;
+    defaultRole?: string;
+    ifNotExists?: boolean;
+    comment?: string;
+    expirePassword?: boolean | Date;
+    accountLocked?: boolean;
+}
+export interface AlterUserOptions {
+    host?: string;
+    password?: string;
+    authPlugin?: string;
+    requireSSL?: boolean | 'NONE';
+    maxConnections?: number;
+    maxQueriesPerHour?: number;
+    maxUpdatesPerHour?: number;
+    maxConnectionsPerHour?: number;
+    passwordExpirePolicy?: 'DEFAULT' | 'NEVER' | 'INTERVAL' | number;
+    accountLocked?: boolean;
+    unlockAccount?: boolean;
+    resetExpiredPassword?: boolean;
+}
+export interface GrantOptions {
+    privileges: PrivilegeType[];
+    on: PrivilegeScope;
+    to: string | string[];
+    host?: string;
+    withGrantOption?: boolean;
+    asUser?: string;
+}
+export interface RevokeOptions {
+    privileges: PrivilegeType[];
+    on: PrivilegeScope;
+    from: string | string[];
+    host?: string;
+    cascade?: boolean;
+    restrict?: boolean;
+    grantOptionFor?: boolean;
+}
+export interface RoleOptions {
+    ifNotExists?: boolean;
+    createRole?: boolean;
+    superuser?: boolean;
+    replication?: boolean;
+    bypassRLS?: boolean;
+    password?: string;
+    inherit?: boolean;
+    login?: boolean;
+    connectionLimit?: number;
+    comment?: string;
+}
+export interface UserInfo {
+    user: string;
+    host: string;
+    plugin?: string;
+    passwordExpired?: boolean;
+    accountLocked?: boolean;
+    createTime?: Date;
+}
+export interface PrivilegeInfo {
+    grantee: string;
+    privilegeType: string;
+    tableSchema?: string;
+    tableName?: string;
+    columnName?: string;
+    isGrantable: boolean;
+}
+/**
+ * Convenience groupings of privilege types by category.
+ */
+export declare const PRIVILEGE_LEVELS: {
+    readonly ALL: PrivilegeType[];
+    readonly READ: PrivilegeType[];
+    readonly WRITE: PrivilegeType[];
+    readonly DDL: PrivilegeType[];
+    readonly DML: PrivilegeType[];
+    readonly ROUTINE: PrivilegeType[];
+    readonly VIEW: PrivilegeType[];
+};
+export declare class UserManager {
+    private prorm;
+    constructor(prorm: any);
+    createUser(username: string, options?: CreateUserOptions): Promise<void>;
+    alterUser(username: string, options: AlterUserOptions): Promise<void>;
+    dropUser(username: string, options?: {
+        host?: string;
+        ifExists?: boolean;
+    }): Promise<void>;
+    getUsers(): Promise<UserInfo[]>;
+    userExists(username: string, host?: string): Promise<boolean>;
+    grant(options: GrantOptions): Promise<void>;
+    revoke(options: RevokeOptions): Promise<void>;
+    showGrants(username: string, host?: string): Promise<PrivilegeInfo[]>;
+    flushPrivileges(): Promise<void>;
+    createRole(roleName: string, options?: RoleOptions): Promise<void>;
+    dropRole(roleName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    grantRole(role: string, to: string | string[], options?: {
+        withAdminOption?: boolean;
+    }): Promise<void>;
+    revokeRole(role: string, from: string | string[], options?: {
+        cascade?: boolean;
+    }): Promise<void>;
+    getRoles(): Promise<string[]>;
+}

package/dist/utils/date.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Date utility functions
+ */
+export interface DateUtils {
+    now: () => Date;
+    today: () => Date;
+    tomorrow: () => Date;
+    yesterday: () => Date;
+    addDays: (date: Date, days: number) => Date;
+    subtractDays: (date: Date, days: number) => Date;
+    addMonths: (date: Date, months: number) => Date;
+    subtractMonths: (date: Date, months: number) => Date;
+    addYears: (date: Date, years: number) => Date;
+    subtractYears: (date: Date, years: number) => Date;
+    format: (date: Date, formatStr?: string) => string;
+    formatISO: (date: Date) => string;
+    formatRelative: (date: Date) => string;
+    isToday: (date: Date) => boolean;
+    isTomorrow: (date: Date) => boolean;
+    isYesterday: (date: Date) => boolean;
+    isSameDay: (date1: Date, date2: Date) => boolean;
+    startOfDay: (date: Date) => Date;
+    endOfDay: (date: Date) => Date;
+    startOfMonth: (date: Date) => Date;
+    endOfMonth: (date: Date) => Date;
+    startOfYear: (date: Date) => Date;
+    endOfYear: (date: Date) => Date;
+    daysBetween: (date1: Date, date2: Date) => number;
+    isValidDate: (date: any) => boolean;
+}
+/**
+ * Get current date/time
+ */
+export declare function now(): Date;
+/**
+ * Get today's date (midnight)
+ */
+export declare function today(): Date;
+/**
+ * Get tomorrow's date (midnight)
+ */
+export declare function tomorrow(): Date;
+/**
+ * Get yesterday's date (midnight)
+ */
+export declare function yesterday(): Date;
+/**
+ * Add days to a date
+ */
+export declare function addDays(date: Date, days: number): Date;
+/**
+ * Subtract days from a date
+ */
+export declare function subtractDays(date: Date, days: number): Date;
+/**
+ * Add months to a date
+ */
+export declare function addMonths(date: Date, months: number): Date;
+/**
+ * Subtract months from a date
+ */
+export declare function subtractMonths(date: Date, months: number): Date;
+/**
+ * Add years to a date
+ */
+export declare function addYears(date: Date, years: number): Date;
+/**
+ * Subtract years from a date
+ */
+export declare function subtractYears(date: Date, years: number): Date;
+/**
+ * Format a date
+ * Format tokens: YYYY, YY, MM, DD, HH, mm, ss
+ *
+ * Note: exported as `formatDate` (not `format`) so it doesn't collide with
+ * the numeric `format(value, decimals)` helper in './index'. Local exports
+ * in index.ts take precedence over this module's `export * from './date'`
+ * re-export for identically-named bindings, so a top-level `utils.format`
+ * pointing at a date formatter would silently break numeric-formatting
+ * callers (and vice versa).
+ */
+export declare function formatDate(date: Date, formatStr?: string): string;
+/**
+ * Format a date (alias for formatDate). Kept for direct
+ * `import { format } from './utils/date'` consumers; not re-exported at the
+ * top-level `utils` barrel under this name (see note above).
+ */
+export declare const format: typeof formatDate;
+/**
+ * Format date as ISO string (YYYY-MM-DD)
+ */
+export declare function formatISO(date: Date): string;
+/**
+ * Get relative time string (e.g., "2 hours ago", "in 3 days")
+ */
+export declare function formatRelative(date: Date): string;
+/**
+ * Check if date is today
+ */
+export declare function isToday(date: Date): boolean;
+/**
+ * Check if date is tomorrow
+ */
+export declare function isTomorrow(date: Date): boolean;
+/**
+ * Check if date is yesterday
+ */
+export declare function isYesterday(date: Date): boolean;
+/**
+ * Check if two dates are the same day
+ */
+export declare function isSameDay(date1: Date, date2: Date): boolean;
+/**
+ * Get start of day (midnight)
+ */
+export declare function startOfDay(date: Date): Date;
+/**
+ * Get end of day (23:59:59.999)
+ */
+export declare function endOfDay(date: Date): Date;
+/**
+ * Get start of month
+ */
+export declare function startOfMonth(date: Date): Date;
+/**
+ * Get end of month
+ */
+export declare function endOfMonth(date: Date): Date;
+/**
+ * Get start of year
+ */
+export declare function startOfYear(date: Date): Date;
+/**
+ * Get end of year
+ */
+export declare function endOfYear(date: Date): Date;
+/**
+ * Get number of days between two dates
+ */
+export declare function daysBetween(date1: Date, date2: Date): number;
+/**
+ * Check if value is a valid date
+ */
+export declare function isValidDate(date: any): boolean;
+/**
+ * Date utilities object for convenient access
+ */
+export declare const dateUtils: DateUtils;
+export default dateUtils;

package/dist/utils/index.d.ts

@@ -0,0 +1,359 @@
+/**
+ * Utility functions for the ORM
+ * Includes string converters, pluralization, object utilities, UUID generation, and SQL formatting
+ */
+import { pad, truncate } from './string';
+/**
+ * Convert camelCase to snake_case
+ */
+export declare function camelToSnake(str: string): string;
+/**
+ * Convert snake_case to camelCase
+ * Alias for snakeToCamel
+ */
+export declare function camelize(str: string): string;
+/**
+ * Convert snake_case to camelCase
+ */
+export declare function snakeToCamel(str: string): string;
+/**
+ * Convert camelCase to snake_case
+ * Alias for camelToSnake
+ */
+export declare function snakeCase(str: string): string;
+/**
+ * Convert camelCase to kebab-case
+ */
+export declare function camelToKebab(str: string): string;
+/**
+ * Convert kebab-case to camelCase
+ */
+export declare function kebabToCamel(str: string): string;
+/**
+ * Pluralize a word
+ */
+export declare function pluralize(word: string, count?: number): string;
+/**
+ * Singularize a word
+ */
+export declare function singularize(word: string): string;
+/**
+ * Deep clone an object
+ */
+export declare function cloneDeep<T>(obj: T): T;
+/**
+ * Deep merge objects
+ */
+export declare function merge<T extends Record<string, any>>(target: T, ...sources: Array<Partial<T>>): T;
+/**
+ * Pick properties from an object
+ */
+export declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * Omit properties from an object
+ */
+export declare function omit<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * Generate a UUID v4
+ */
+export declare function generateUUID(): string;
+/**
+ * Generate a short UUID (8 characters)
+ */
+export declare function generateShortUUID(): string;
+/**
+ * Validate UUID format
+ */
+export declare function isValidUUID(uuid: string): boolean;
+/**
+ * Format values for SQL query
+ */
+export declare function formatValues(values: Record<string, any>): Record<string, any>;
+/**
+ * Format a single value for SQL
+ */
+export declare function formatValue(value: any): any;
+/**
+ * Escape a string for SQL
+ */
+export declare function escapeString(value: string): string;
+/**
+ * Escape an identifier (table/column name)
+ */
+export declare function escapeId(identifier: string): string;
+/**
+ * Format a where condition for SQL
+ */
+export declare function formatWhere(where: Record<string, any>): string;
+/**
+ * Check if value is empty (null, undefined, empty string, empty array, empty object)
+ */
+export declare function isEmpty(value: any): boolean;
+/**
+ * Get the first defined value from arguments
+ */
+export declare function coalesce<T>(...values: (T | undefined | null)[]): T | undefined;
+/**
+ * Convert a value to a string suitable for use in SQL LIKE
+ */
+export declare function escapeLike(value: string): string;
+/**
+ * Wrap a string in backticks (for SQL identifiers)
+ */
+export declare function addTicks(str: string): string;
+/**
+ * Remove backticks from a string
+ */
+export declare function removeTicks(str: string): string;
+/**
+ * Supported SQL dialects
+ */
+export type Dialect = 'mysql' | 'postgres' | 'sqlite' | 'mariadb' | 'mssql';
+/**
+ * Convert a value to its default JavaScript value
+ */
+export declare function toDefaultValue(value: any): any;
+/**
+ * Format a value for SQL based on dialect
+ */
+export declare function formatDefaultValue(value: any, dialect?: Dialect): string;
+/**
+ * Insert a string at a specific position, optionally replacing characters
+ * @param str The original string
+ * @param index Position to insert/replace at (0-indexed)
+ * @param count Number of characters to replace (0 for insert only)
+ * @param insert String to insert
+ */
+export declare function spliceStr(str: string, index: number, count: number, insert: string): string;
+/**
+ * Format a date to a string
+ * @param date - Date to format
+ * @param formatStr - Format string (YYYY-MM-DD, etc.)
+ */
+export declare function formatDateString(date: Date | string | number, formatStr?: string): string;
+/**
+ * Generate a random string of specified length
+ */
+export declare function randomString(length?: number, chars?: string): string;
+/**
+ * Generate a random alphanumeric string
+ */
+export declare function randomAlphaNumeric(length?: number): string;
+/**
+ * Generate a random numeric string
+ */
+export declare function randomNumeric(length?: number): string;
+/**
+ * Generate a random hex string
+ */
+export declare function randomHex(length?: number): string;
+/**
+ * Get current timestamp in milliseconds
+ *
+ * Note: named `timestamp` (not `now`) to avoid colliding with the
+ * `now(): Date` export from './date', which is re-exported via
+ * `export * from './date'` below and is the canonical `utils.now()`.
+ */
+export declare function timestamp(): number;
+/**
+ * Get current timestamp as Date object
+ */
+export declare function nowDate(): Date;
+/**
+ * Return default value if value is null or undefined
+ */
+export declare function defaultValue<T>(value: T | null | undefined, defaultVal: T): T;
+/**
+ * Return default value if value is empty
+ */
+export declare function defaultIfEmpty<T>(value: T, defaultVal: T): T;
+export interface RetryConfig {
+    /** Maximum number of retry attempts */
+    max?: number;
+    /** Timeout in milliseconds between retries */
+    timeout?: number;
+    /** Array of error message patterns to retry on */
+    match?: string[];
+    /** Enable exponential backoff (default: false) */
+    backoff?: boolean;
+    /** Base multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum backoff time in ms (default: 10000) */
+    backoffMax?: number;
+}
+/**
+ * Retry a function with configurable options
+ *
+ * @param fn - The async function to retry
+ * @param options - Retry options
+ * @returns The result of the function
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryConfig): Promise<T>;
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn - The async function to retry
+ * @param maxRetries - Maximum number of retries (default: 3)
+ * @param baseTimeout - Base timeout in ms (default: 1000)
+ * @param maxTimeout - Maximum timeout in ms (default: 10000)
+ * @returns The result of the function
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries?: number, baseTimeout?: number, maxTimeout?: number): Promise<T>;
+/**
+ * Get unique values from an array
+ */
+export declare function unique<T>(arr: T[]): T[];
+/**
+ * Flatten an array of arrays
+ */
+export declare function flatten<T>(arr: T[][]): T[];
+/**
+ * Group array items by a key
+ */
+export declare function groupBy<T extends Record<string, any>>(arr: T[], key: keyof T | string): Record<string, T[]>;
+/**
+ * Sort array by a key or function
+ */
+export declare function sortBy<T>(arr: T[], iteratee: keyof T | ((item: T) => any)): T[];
+/**
+ * Sum array values
+ */
+export declare function sum(arr: number[]): number;
+/**
+ * Convert string to snake_case (alias for snakeCase)
+ */
+export declare function underscore(str: string): string;
+/**
+ * String includes method
+ */
+export declare function includes(str: string, searchString: string): boolean;
+/**
+ * String startsWith method
+ */
+export declare function startsWith(str: string, searchString: string): boolean;
+/**
+ * String endsWith method
+ */
+export declare function endsWith(str: string, searchString: string): boolean;
+/**
+ * String repeat method
+ */
+export declare function repeat(str: string, count: number): string;
+/**
+ * Reverse a string or an array.
+ *
+ * Overloaded so `reverse('hello')` returns `'olleh'` (a string) while
+ * `reverse([1, 2, 3])` returns `[3, 2, 1]` (an array), instead of always
+ * spreading the input into a character/element array.
+ */
+export declare function reverse(str: string): string;
+export declare function reverse<T>(arr: T[]): T[];
+/**
+ * Deep clone an object
+ */
+export declare function clone<T>(obj: T): T;
+/**
+ * Get property from object
+ */
+export declare function get(obj: any, path: string): any;
+/**
+ * Set property on object
+ */
+export declare function set(obj: any, path: string, value: any): void;
+/**
+ * Check if object has property
+ */
+export declare function has(obj: any, path: string): boolean;
+/**
+ * Check if value is a string
+ */
+export declare function isString(value: any): value is string;
+/**
+ * Check if value is a number
+ */
+export declare function isNumber(value: any): value is number;
+/**
+ * Check if value is a boolean
+ */
+export declare function isBoolean(value: any): value is boolean;
+/**
+ * Check if value is a date
+ */
+export declare function isDate(value: any): value is Date;
+/**
+ * Check if value is an array
+ */
+export declare function isArray(value: any): value is any[];
+/**
+ * Check if value is an object
+ */
+export declare function isObject(value: any): value is object;
+/**
+ * Format a number as currency
+ */
+export declare function formatCurrency(amount: number, currency?: string): string;
+/**
+ * Format a number to a fixed number of decimal places.
+ *
+ * Named `format` (not re-exported by './date', see note there) so this is
+ * the canonical `utils.format` for numeric formatting.
+ */
+export declare function format(value: number, decimals?: number): string;
+export * from './string';
+export * from './date';
+declare const _default: {
+    camelToSnake: typeof camelToSnake;
+    snakeToCamel: typeof snakeToCamel;
+    camelToKebab: typeof camelToKebab;
+    kebabToCamel: typeof kebabToCamel;
+    camelize: typeof camelize;
+    snakeCase: typeof snakeCase;
+    pluralize: typeof pluralize;
+    singularize: typeof singularize;
+    cloneDeep: typeof cloneDeep;
+    merge: typeof merge;
+    pick: typeof pick;
+    omit: typeof omit;
+    generateUUID: typeof generateUUID;
+    generateShortUUID: typeof generateShortUUID;
+    isValidUUID: typeof isValidUUID;
+    formatValues: typeof formatValues;
+    formatValue: typeof formatValue;
+    escapeString: typeof escapeString;
+    escapeId: typeof escapeId;
+    formatWhere: typeof formatWhere;
+    isEmpty: typeof isEmpty;
+    coalesce: typeof coalesce;
+    truncate: typeof truncate;
+    pad: typeof pad;
+    escapeLike: typeof escapeLike;
+    addTicks: typeof addTicks;
+    removeTicks: typeof removeTicks;
+    toDefaultValue: typeof toDefaultValue;
+    formatDefaultValue: typeof formatDefaultValue;
+    spliceStr: typeof spliceStr;
+    unique: typeof unique;
+    flatten: typeof flatten;
+    groupBy: typeof groupBy;
+    sortBy: typeof sortBy;
+    sum: typeof sum;
+    underscore: typeof underscore;
+    includes: typeof includes;
+    startsWith: typeof startsWith;
+    endsWith: typeof endsWith;
+    repeat: typeof repeat;
+    reverse: typeof reverse;
+    clone: typeof clone;
+    get: typeof get;
+    set: typeof set;
+    has: typeof has;
+    isString: typeof isString;
+    isNumber: typeof isNumber;
+    isBoolean: typeof isBoolean;
+    isDate: typeof isDate;
+    isArray: typeof isArray;
+    isObject: typeof isObject;
+    formatCurrency: typeof formatCurrency;
+    formatDateString: typeof formatDateString;
+};
+export default _default;