@plyaz/db 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +169 -0
  2. package/dist/adapters/drizzle/DrizzleAdapter.d.ts +269 -0
  3. package/dist/adapters/drizzle/DrizzleAdapter.d.ts.map +1 -0
  4. package/dist/adapters/index.d.ts +20 -0
  5. package/dist/adapters/index.d.ts.map +1 -0
  6. package/dist/adapters/sql/SQLAdapter.d.ts +282 -0
  7. package/dist/adapters/sql/SQLAdapter.d.ts.map +1 -0
  8. package/dist/adapters/supabase/SupabaseAdapter.d.ts +305 -0
  9. package/dist/adapters/supabase/SupabaseAdapter.d.ts.map +1 -0
  10. package/dist/advanced/backup/BackupService.d.ts +159 -0
  11. package/dist/advanced/backup/BackupService.d.ts.map +1 -0
  12. package/dist/advanced/backup/index.d.ts +2 -0
  13. package/dist/advanced/backup/index.d.ts.map +1 -0
  14. package/dist/advanced/caching/CacheEvict.decorator.d.ts +3 -0
  15. package/dist/advanced/caching/CacheEvict.decorator.d.ts.map +1 -0
  16. package/dist/advanced/caching/Cacheable.decorator.d.ts +99 -0
  17. package/dist/advanced/caching/Cacheable.decorator.d.ts.map +1 -0
  18. package/dist/advanced/caching/RedisCache.d.ts +417 -0
  19. package/dist/advanced/caching/RedisCache.d.ts.map +1 -0
  20. package/dist/advanced/caching/index.d.ts +4 -0
  21. package/dist/advanced/caching/index.d.ts.map +1 -0
  22. package/dist/advanced/connection-pool/DynamicPool.d.ts +234 -0
  23. package/dist/advanced/connection-pool/DynamicPool.d.ts.map +1 -0
  24. package/dist/advanced/connection-pool/index.d.ts +2 -0
  25. package/dist/advanced/connection-pool/index.d.ts.map +1 -0
  26. package/dist/advanced/index.d.ts +8 -0
  27. package/dist/advanced/index.d.ts.map +1 -0
  28. package/dist/advanced/monitoring/AlertManager.d.ts +72 -0
  29. package/dist/advanced/monitoring/AlertManager.d.ts.map +1 -0
  30. package/dist/advanced/monitoring/MetricsCollector.d.ts +81 -0
  31. package/dist/advanced/monitoring/MetricsCollector.d.ts.map +1 -0
  32. package/dist/advanced/monitoring/index.d.ts +3 -0
  33. package/dist/advanced/monitoring/index.d.ts.map +1 -0
  34. package/dist/advanced/multi-tenancy/TenantContext.d.ts +52 -0
  35. package/dist/advanced/multi-tenancy/TenantContext.d.ts.map +1 -0
  36. package/dist/advanced/multi-tenancy/TenantRepository.d.ts +292 -0
  37. package/dist/advanced/multi-tenancy/TenantRepository.d.ts.map +1 -0
  38. package/dist/advanced/multi-tenancy/index.d.ts +3 -0
  39. package/dist/advanced/multi-tenancy/index.d.ts.map +1 -0
  40. package/dist/advanced/read-replica/ReadReplicaAdapter.d.ts +516 -0
  41. package/dist/advanced/read-replica/ReadReplicaAdapter.d.ts.map +1 -0
  42. package/dist/advanced/read-replica/ReadReplicaManager.d.ts +68 -0
  43. package/dist/advanced/read-replica/ReadReplicaManager.d.ts.map +1 -0
  44. package/dist/advanced/read-replica/UseReplica.decorator.d.ts +24 -0
  45. package/dist/advanced/read-replica/UseReplica.decorator.d.ts.map +1 -0
  46. package/dist/advanced/read-replica/index.d.ts +3 -0
  47. package/dist/advanced/read-replica/index.d.ts.map +1 -0
  48. package/dist/advanced/sharding/ShardKey.d.ts +80 -0
  49. package/dist/advanced/sharding/ShardKey.d.ts.map +1 -0
  50. package/dist/advanced/sharding/ShardRouter.d.ts +66 -0
  51. package/dist/advanced/sharding/ShardRouter.d.ts.map +1 -0
  52. package/dist/advanced/sharding/index.d.ts +3 -0
  53. package/dist/advanced/sharding/index.d.ts.map +1 -0
  54. package/dist/builder/query/index.d.ts +7 -0
  55. package/dist/builder/query/index.d.ts.map +1 -0
  56. package/dist/builder/query/orm.d.ts +22 -0
  57. package/dist/builder/query/orm.d.ts.map +1 -0
  58. package/dist/builder/query/sql.d.ts +29 -0
  59. package/dist/builder/query/sql.d.ts.map +1 -0
  60. package/dist/extensions/AuditExtension.d.ts +468 -0
  61. package/dist/extensions/AuditExtension.d.ts.map +1 -0
  62. package/dist/extensions/CachingAdapter.d.ts +451 -0
  63. package/dist/extensions/CachingAdapter.d.ts.map +1 -0
  64. package/dist/extensions/EncryptionExtension.d.ts +95 -0
  65. package/dist/extensions/EncryptionExtension.d.ts.map +1 -0
  66. package/dist/extensions/ReadReplicaAdapter.d.ts +32 -0
  67. package/dist/extensions/ReadReplicaAdapter.d.ts.map +1 -0
  68. package/dist/extensions/SoftDeleteExtension.d.ts +430 -0
  69. package/dist/extensions/SoftDeleteExtension.d.ts.map +1 -0
  70. package/dist/extensions/index.d.ts +79 -0
  71. package/dist/extensions/index.d.ts.map +1 -0
  72. package/dist/factory/AdapterFactory.d.ts +111 -0
  73. package/dist/factory/AdapterFactory.d.ts.map +1 -0
  74. package/dist/factory/createDatabaseService.d.ts +121 -0
  75. package/dist/factory/createDatabaseService.d.ts.map +1 -0
  76. package/dist/index.cjs +8518 -0
  77. package/dist/index.cjs.map +1 -0
  78. package/dist/index.d.ts +19 -0
  79. package/dist/index.d.ts.map +1 -0
  80. package/dist/index.mjs +8480 -0
  81. package/dist/index.mjs.map +1 -0
  82. package/dist/repository/BaseRepository.d.ts +209 -0
  83. package/dist/repository/BaseRepository.d.ts.map +1 -0
  84. package/dist/repository/index.d.ts +80 -0
  85. package/dist/repository/index.d.ts.map +1 -0
  86. package/dist/security/index.cjs +118 -0
  87. package/dist/security/index.cjs.map +1 -0
  88. package/dist/security/index.d.ts +3 -0
  89. package/dist/security/index.d.ts.map +1 -0
  90. package/dist/security/index.mjs +114 -0
  91. package/dist/security/index.mjs.map +1 -0
  92. package/dist/security/sanitizers/html.sanitizer.d.ts +31 -0
  93. package/dist/security/sanitizers/html.sanitizer.d.ts.map +1 -0
  94. package/dist/security/serializers/DataValidation.d.ts +34 -0
  95. package/dist/security/serializers/DataValidation.d.ts.map +1 -0
  96. package/dist/service/DatabaseService.d.ts +136 -0
  97. package/dist/service/DatabaseService.d.ts.map +1 -0
  98. package/dist/service/EventEmitter.d.ts +110 -0
  99. package/dist/service/EventEmitter.d.ts.map +1 -0
  100. package/dist/service/HealthManager.d.ts +166 -0
  101. package/dist/service/HealthManager.d.ts.map +1 -0
  102. package/dist/utils/ConfigMerger.d.ts +227 -0
  103. package/dist/utils/ConfigMerger.d.ts.map +1 -0
  104. package/dist/utils/databaseResultHelpers.d.ts +98 -0
  105. package/dist/utils/databaseResultHelpers.d.ts.map +1 -0
  106. package/dist/utils/index.d.ts +7 -0
  107. package/dist/utils/index.d.ts.map +1 -0
  108. package/dist/utils/normalizeDetails.d.ts +111 -0
  109. package/dist/utils/normalizeDetails.d.ts.map +1 -0
  110. package/dist/utils/pagination.d.ts +77 -0
  111. package/dist/utils/pagination.d.ts.map +1 -0
  112. package/dist/utils/regex.d.ts +199 -0
  113. package/dist/utils/regex.d.ts.map +1 -0
  114. package/dist/utils/typeGuards.d.ts +57 -0
  115. package/dist/utils/typeGuards.d.ts.map +1 -0
  116. package/dist/utils/validation.d.ts +146 -0
  117. package/dist/utils/validation.d.ts.map +1 -0
  118. package/package.json +156 -0
@@ -0,0 +1,98 @@
1
+ /**
2
+ * @fileoverview Database Result Helper Functions for @plyaz/db package
3
+ *
4
+ * This module provides utility functions for creating standardized DatabaseResult objects
5
+ * used throughout the @plyaz/db package. These helpers ensure consistent result formatting
6
+ * across all database operations and adapters.
7
+ *
8
+ * Part of the @plyaz/db package - a TypeScript database abstraction layer with
9
+ * support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
10
+ * soft delete), and advanced features (caching, read replicas, multi-tenancy).
11
+ *
12
+ */
13
+ import type { DatabaseResult } from "@plyaz/types/db";
14
+ /**
15
+ * Creates a successful DatabaseResult wrapper for operation results
16
+ *
17
+ * Used throughout all database adapters and extensions to wrap successful operation results
18
+ * in a consistent format. This enables standardized error handling and result processing
19
+ * across the entire @plyaz/db package.
20
+ *
21
+ * **Used by:**
22
+ * - All database adapters (DrizzleAdapter, SupabaseAdapter, SQLAdapter)
23
+ * - All extensions (AuditAdapter, EncryptionAdapter, SoftDeleteAdapter, etc.)
24
+ * - DatabaseService for operation results
25
+ * - Repository layer for consistent return types
26
+ *
27
+ * @template T - The type of the successful result value
28
+ * @param {T} value - The successful result value to wrap
29
+ * @returns {DatabaseResult<T>} A success result object with the value
30
+ *
31
+ * @example
32
+ * ```typescript
33
+ * import { success } from '@plyaz/db/utils';
34
+ *
35
+ * // In adapter methods
36
+ * async findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>> {
37
+ * try {
38
+ * const record = await this.db.select().from(table).where(eq(id));
39
+ * return success(record[0] || null); // Wrap successful result
40
+ * } catch (error) {
41
+ * return failure(new DatabaseError('FIND_FAILED', error.message));
42
+ * }
43
+ * }
44
+ *
45
+ * // In service methods
46
+ * const userResult = await userRepository.findById('user-123');
47
+ * if (userResult.success) {
48
+ * console.log('Found user:', userResult.value.name);
49
+ * }
50
+ * ```
51
+ *
52
+ */
53
+ export declare function success<T = null>(value?: T): DatabaseResult<T>;
54
+ /**
55
+ * Creates a failed DatabaseResult wrapper for operation errors
56
+ *
57
+ * Used throughout all database adapters and extensions to wrap error results
58
+ * in a consistent format. This enables standardized error handling and result processing
59
+ * across the entire @plyaz/db package.
60
+ *
61
+ * **Used by:**
62
+ * - All database adapters for error cases
63
+ * - All extensions for error propagation
64
+ * - DatabaseService for operation failures
65
+ * - Repository layer for consistent error handling
66
+ *
67
+ * @template T - The type that would have been returned on success
68
+ * @param {Error} error - The error that occurred during the operation
69
+ * @returns {DatabaseResult<T>} A failure result object with the error
70
+ *
71
+ * @example
72
+ * ```typescript
73
+ * import { failure } from '@plyaz/db/utils';
74
+ * import { DatabaseError } from '@plyaz/errors';
75
+ import { DATABASE_ERROR_CODES } from '@plyaz/types/errors';
76
+ *
77
+ * // In adapter methods
78
+ * async create<T>(table: string, data: T): Promise<DatabaseResult<T>> {
79
+ * try {
80
+ * const result = await this.db.insert(table).values(data).returning();
81
+ * return success(result[0]);
82
+ * } catch (error) {
83
+ * return failure(new DatabaseError(
84
+ * `Failed to create record: ${error.message}`));
85
+ * }
86
+ * }
87
+ *
88
+ * // In service layer error handling
89
+ * const createResult = await userRepository.create(userData);
90
+ * if (!createResult.success) {
91
+ * logger.error('User creation failed:', createResult.error.message);
92
+ * throw createResult.error;
93
+ * }
94
+ * ```
95
+ *
96
+ */
97
+ export declare function failure<T>(error: Error): DatabaseResult<T>;
98
+ //# sourceMappingURL=databaseResultHelpers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"databaseResultHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/databaseResultHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,GAAE,CAAa,GAAG,cAAc,CAAC,CAAC,CAAC,CAEzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,CAE1D"}
@@ -0,0 +1,7 @@
1
+ export * from "./typeGuards";
2
+ export * from "./validation";
3
+ export * from "./databaseResultHelpers";
4
+ export * from "./pagination";
5
+ export * from "./ConfigMerger";
6
+ export * from "./normalizeDetails";
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}
@@ -0,0 +1,111 @@
1
+ /**
2
+ * @fileoverview Detail Normalization Utilities for @plyaz/db package
3
+ *
4
+ * This module provides utilities for normalizing various data types into consistent
5
+ * string-based record formats. Used throughout the @plyaz/db package for standardizing
6
+ * error details, health status information, and event metadata.
7
+ *
8
+ * Part of the @plyaz/db package - a TypeScript database abstraction layer with
9
+ * support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
10
+ * soft delete), and advanced features (caching, read replicas, multi-tenancy).
11
+ *
12
+ */
13
+ /**
14
+ * Normalizes any input into a standardized Record<string, string> format
15
+ *
16
+ * Converts various data types into a consistent string-based record format
17
+ * for use in error details, health status information, and event metadata.
18
+ * Provides safe handling of different input types with fallback strategies.
19
+ *
20
+ * **Normalization Rules:**
21
+ * - Objects: Converts all property values to strings while preserving keys
22
+ * - Primitives: Wraps in { info: stringValue } format
23
+ * - null/undefined: Returns undefined (no details)
24
+ * - Arrays: Converts to { info: stringified array }
25
+ * - Errors: Safely handles conversion failures
26
+ *
27
+ * **Used by:**
28
+ * - HealthManager for health status details
29
+ * - DatabaseEventEmitter for event metadata
30
+ * - Error handling throughout adapter chain
31
+ * - Audit logging for consistent detail formatting
32
+ *
33
+ * @param {unknown} details - Input details of any type to normalize
34
+ * @returns {Record<string, string> | undefined} Normalized details as string record or undefined
35
+ *
36
+ * @example
37
+ * ```typescript
38
+ * import { normalizeDetails } from '@plyaz/db/utils';
39
+ *
40
+ * // Object normalization
41
+ * const objDetails = normalizeDetails({
42
+ * count: 42,
43
+ * active: true,
44
+ * name: 'test'
45
+ * });
46
+ * console.log(objDetails);
47
+ * // { count: "42", active: "true", name: "test" }
48
+ *
49
+ * // Primitive normalization
50
+ * const stringDetails = normalizeDetails("Connection timeout");
51
+ * console.log(stringDetails);
52
+ * // { info: "Connection timeout" }
53
+ *
54
+ * // Number normalization
55
+ * const numberDetails = normalizeDetails(404);
56
+ * console.log(numberDetails);
57
+ * // { info: "404" }
58
+ *
59
+ * // Null/undefined handling
60
+ * const nullDetails = normalizeDetails(null);
61
+ * console.log(nullDetails);
62
+ * // undefined
63
+ *
64
+ * // Array normalization
65
+ * const arrayDetails = normalizeDetails(['error1', 'error2']);
66
+ * console.log(arrayDetails);
67
+ * // { info: "error1,error2" }
68
+ *
69
+ * // Error object normalization
70
+ * const errorDetails = normalizeDetails(new Error('Database error'));
71
+ * console.log(errorDetails);
72
+ * // { info: "Error: Database error" }
73
+ * ```
74
+ *
75
+ * @example
76
+ * ### Usage in Health Status
77
+ * ```typescript
78
+ * // In HealthManager.checkHealth()
79
+ * const healthStatus = {
80
+ * isHealthy: true,
81
+ * responseTime: 150,
82
+ * details: normalizeDetails({
83
+ * adapter: 'drizzle',
84
+ * connections: 5,
85
+ * lastQuery: new Date()
86
+ * })
87
+ * };
88
+ * // details: { adapter: "drizzle", connections: "5", lastQuery: "2024-01-01T10:00:00.000Z" }
89
+ * ```
90
+ *
91
+ * @example
92
+ * ### Usage in Error Handling
93
+ * ```typescript
94
+ * // In adapter error handling
95
+ * catch (error) {
96
+ * return failure(new DatabaseError(
97
+ * 'QUERY_FAILED',
98
+ * HTTP_STATUS.INTERNAL_SERVER_ERROR,
99
+ * 'Query execution failed',
100
+ * normalizeDetails({
101
+ * query: sql,
102
+ * params: queryParams,
103
+ * originalError: error.message
104
+ * })
105
+ * ));
106
+ * }
107
+ * ```
108
+ *
109
+ */
110
+ export declare function normalizeDetails(details: unknown): Record<string, string> | undefined;
111
+ //# sourceMappingURL=normalizeDetails.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"normalizeDetails.d.ts","sourceRoot":"","sources":["../../src/utils/normalizeDetails.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CA8BpC"}
@@ -0,0 +1,77 @@
1
+ /**
2
+ * @fileoverview Pagination Utilities for @plyaz/db package
3
+ *
4
+ * This module provides pagination calculation utilities used across all database adapters
5
+ * to generate consistent pagination metadata for query results. Supports offset-based
6
+ * pagination with page calculation and validation.
7
+ *
8
+ * Part of the @plyaz/db package - a TypeScript database abstraction layer with
9
+ * support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
10
+ * soft delete), and advanced features (caching, read replicas, multi-tenancy).
11
+ *
12
+ * @module pagination
13
+ */
14
+ import type { PaginationInfo, PaginationOptions } from "@plyaz/types";
15
+ /**
16
+ * Calculates comprehensive pagination metadata for database query results
17
+ *
18
+ * Generates pagination information used by all database adapters to provide
19
+ * consistent pagination metadata in query results. Supports both paginated
20
+ * and non-paginated queries with automatic page calculation.
21
+ *
22
+ * **Used by:**
23
+ * - DrizzleAdapter.findMany() for ORM-based pagination
24
+ * - SupabaseAdapter.findMany() for Supabase pagination
25
+ * - SQLAdapter.findMany() for raw SQL pagination
26
+ * - All repository methods that return paginated results
27
+ *
28
+ * **Calculation Logic:**
29
+ * - Page numbers are 1-based (first page = 1)
30
+ * - Current page = floor(offset / limit) + 1
31
+ * - Total pages = ceil(total / limit)
32
+ * - Handles edge cases (no limit, empty results, etc.)
33
+ *
34
+ * @param {number} total - Total number of items matching the query
35
+ * @param {PaginationOptions} [options] - Optional pagination configuration
36
+ * @param {number} [options.limit] - Maximum items per page
37
+ * @param {number} [options.offset] - Number of items to skip (default: 0)
38
+ * @returns {PaginationInfo} Complete pagination metadata object
39
+ *
40
+ * @example
41
+ * ```typescript
42
+ * import { calculatePagination } from '@plyaz/db/utils';
43
+ *
44
+ * // Standard pagination (page 2 of 20 items per page)
45
+ * const pagination1 = calculatePagination(100, { limit: 20, offset: 20 });
46
+ * console.log(pagination1);
47
+ * // {
48
+ * // page: 2,
49
+ * // limit: 20,
50
+ * // offset: 20,
51
+ * // totalPages: 5
52
+ * // }
53
+ *
54
+ * // First page
55
+ * const pagination2 = calculatePagination(100, { limit: 20, offset: 0 });
56
+ * console.log(pagination2);
57
+ * // {
58
+ * // page: 1,
59
+ * // limit: 20,
60
+ * // offset: 0,
61
+ * // totalPages: 5
62
+ * // }
63
+ *
64
+ * // No pagination (return all results)
65
+ * const pagination3 = calculatePagination(100);
66
+ * console.log(pagination3);
67
+ * // {
68
+ * // page: undefined,
69
+ * // limit: undefined,
70
+ * // offset: 0,
71
+ * // totalPages: undefined
72
+ * // }
73
+ * ```
74
+ *
75
+ */
76
+ export declare function calculatePagination(total: number, options?: PaginationOptions): PaginationInfo;
77
+ //# sourceMappingURL=pagination.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAiFtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,CAyBhB"}
@@ -0,0 +1,199 @@
1
+ /**
2
+ * @fileoverview Centralized Regex Patterns for @plyaz/db package
3
+ *
4
+ * This module contains all regex patterns used throughout the database package.
5
+ * Centralizing regex patterns improves maintainability, reusability, and consistency.
6
+ *
7
+ * Part of the @plyaz/db package - a TypeScript database abstraction layer with
8
+ * support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
9
+ * soft delete), and advanced features (caching, read replicas, multi-tenancy).
10
+ *
11
+ */
12
+ /**
13
+ * Database field and table name validation patterns
14
+ * Used for SQL injection prevention and database identifier validation
15
+ */
16
+ export declare const DATABASE_PATTERNS: {
17
+ /**
18
+ * Validates database field names (columns)
19
+ * - Must start with letter (a-z, A-Z) or underscore (_)
20
+ * - Can contain letters, numbers, and underscores
21
+ * - Prevents SQL injection through field names
22
+ *
23
+ * Used in: validation.ts, sql.ts, DrizzleAdapter.ts, SQLAdapter.ts
24
+ */
25
+ readonly FIELD_NAME: RegExp;
26
+ /**
27
+ * Validates database table names
28
+ * - Same rules as field names for consistency
29
+ * - Follows SQL identifier naming conventions
30
+ *
31
+ * Used in: validation.ts, CacheEvict.decorator.ts
32
+ */
33
+ readonly TABLE_NAME: RegExp;
34
+ };
35
+ /**
36
+ * Cache key validation patterns
37
+ * Used for validating cache keys and patterns in caching system
38
+ */
39
+ export declare const CACHE_PATTERNS: {
40
+ /**
41
+ * Validates cache keys
42
+ * - Allows letters, numbers, colons, underscores, and hyphens
43
+ * - Used for Redis cache key validation
44
+ *
45
+ * Used in: CacheEvict.decorator.ts
46
+ */
47
+ readonly CACHE_KEY: RegExp;
48
+ /**
49
+ * Validates cache patterns (with wildcards)
50
+ * - Same as cache key but allows asterisk (*) for wildcards
51
+ * - Used for cache pattern matching and eviction
52
+ *
53
+ * Used in: CacheEvict.decorator.ts
54
+ */
55
+ readonly CACHE_PATTERN: RegExp;
56
+ };
57
+ /**
58
+ * SQL query sanitization patterns
59
+ * Used for cleaning and normalizing SQL queries for metrics and logging
60
+ */
61
+ export declare const SQL_PATTERNS: {
62
+ /**
63
+ * Matches PostgreSQL parameter placeholders ($1, $2, etc.)
64
+ * - Used to normalize parameterized queries for metrics
65
+ *
66
+ * Used in: MetricsCollector.ts
67
+ */
68
+ readonly POSTGRES_PARAMS: RegExp;
69
+ /**
70
+ * Matches numeric values in SQL queries
71
+ * - Used to replace numbers with placeholders for query normalization
72
+ *
73
+ * Used in: MetricsCollector.ts
74
+ */
75
+ readonly NUMERIC_VALUES: RegExp;
76
+ /**
77
+ * Matches string literals in SQL queries (single quotes)
78
+ * - Used to replace string values with placeholders
79
+ *
80
+ * Used in: MetricsCollector.ts
81
+ */
82
+ readonly STRING_LITERALS: RegExp;
83
+ };
84
+ /**
85
+ * Input sanitization patterns
86
+ * Used for cleaning user input and preventing injection attacks
87
+ */
88
+ export declare const SANITIZATION_PATTERNS: {
89
+ /**
90
+ * Matches dangerous characters for SQL injection prevention
91
+ * - Null byte, backspace, tab, newline, carriage return
92
+ * - Single and double quotes, backslashes, percent signs
93
+ *
94
+ * Used in: validation.ts (sanitizeInput function)
95
+ */
96
+ readonly DANGEROUS_CHARS: RegExp;
97
+ /**
98
+ * Matches shell metacharacters for command injection prevention
99
+ * - Semicolon, ampersand, pipe, backtick, dollar, parentheses, etc.
100
+ *
101
+ * Used in: BackupService.ts (sanitizeCommand function)
102
+ */
103
+ readonly SHELL_METACHARACTERS: RegExp;
104
+ /**
105
+ * Matches multiple whitespace characters
106
+ * - Used to normalize whitespace in sanitized input
107
+ *
108
+ * Used in: BackupService.ts
109
+ */
110
+ readonly MULTIPLE_WHITESPACE: RegExp;
111
+ /**
112
+ * Matches line breaks and tabs
113
+ * - Used to replace line breaks with spaces
114
+ *
115
+ * Used in: BackupService.ts
116
+ */
117
+ readonly LINE_BREAKS_TABS: RegExp;
118
+ /**
119
+ * Matches Unicode control characters
120
+ * - Uses Unicode property escape to match all control characters
121
+ *
122
+ * Used in: BackupService.ts
123
+ */
124
+ readonly CONTROL_CHARACTERS: RegExp;
125
+ };
126
+ /**
127
+ * File and path patterns
128
+ * Used for file operations and path validation
129
+ */
130
+ export declare const FILE_PATTERNS: {
131
+ /**
132
+ * Matches colon and dot characters in timestamps
133
+ * - Used to create filesystem-safe timestamps
134
+ *
135
+ * Used in: BackupService.ts (timestamp generation)
136
+ */
137
+ readonly TIMESTAMP_CHARS: RegExp;
138
+ };
139
+ /**
140
+ * Utility functions for common regex operations
141
+ */
142
+ export declare const DB_REGEX: {
143
+ /**
144
+ * Tests if a string matches the database field name pattern
145
+ * @param fieldName - The field name to validate
146
+ * @returns True if valid database field name
147
+ */
148
+ readonly isValidFieldName: (fieldName: string) => boolean;
149
+ /**
150
+ * Tests if a string matches the database table name pattern
151
+ * @param tableName - The table name to validate
152
+ * @returns True if valid database table name
153
+ */
154
+ readonly isValidTableName: (tableName: string) => boolean;
155
+ /**
156
+ * Tests if a string matches the cache key pattern
157
+ * @param cacheKey - The cache key to validate
158
+ * @returns True if valid cache key
159
+ */
160
+ readonly isValidCacheKey: (cacheKey: string) => boolean;
161
+ /**
162
+ * Tests if a string matches the cache pattern (with wildcards)
163
+ * @param cachePattern - The cache pattern to validate
164
+ * @returns True if valid cache pattern
165
+ */
166
+ readonly isValidCachePattern: (cachePattern: string) => boolean;
167
+ /**
168
+ * Normalizes SQL query by replacing parameters and values with placeholders
169
+ * @param query - The SQL query to normalize
170
+ * @returns Normalized query string
171
+ */
172
+ readonly normalizeSqlQuery: (query: string) => string;
173
+ /**
174
+ * Sanitizes input by escaping dangerous characters
175
+ * @param input - The input string to sanitize
176
+ * @param escapeMap - Map of characters to their escaped equivalents
177
+ * @returns Sanitized string
178
+ */
179
+ readonly sanitizeDangerousChars: (input: string, escapeMap: Record<string, string>) => string;
180
+ /**
181
+ * Creates filesystem-safe timestamp string
182
+ * @param timestamp - ISO timestamp string
183
+ * @returns Filesystem-safe timestamp
184
+ */
185
+ readonly createSafeTimestamp: (timestamp: string) => string;
186
+ /**
187
+ * Sanitizes command string by removing shell metacharacters
188
+ * @param command - Command string to sanitize
189
+ * @returns Sanitized command string
190
+ */
191
+ readonly sanitizeCommand: (command: string) => string;
192
+ /**
193
+ * Sanitizes log message by normalizing whitespace and removing control characters
194
+ * @param message - Log message to sanitize
195
+ * @returns Sanitized log message
196
+ */
197
+ readonly sanitizeLogMessage: (message: string) => string;
198
+ };
199
+ //# sourceMappingURL=regex.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"regex.d.ts","sourceRoot":"","sources":["../../src/utils/regex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;;;;;;OAOG;;IAGH;;;;;;OAMG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,qBAAqB;IAChC;;;;;;OAMG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB;;;;;OAKG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;OAIG;2CAC2B,MAAM,KAAG,OAAO;IAI9C;;;;OAIG;2CAC2B,MAAM,KAAG,OAAO;IAI9C;;;;OAIG;yCACyB,MAAM,KAAG,OAAO;IAI5C;;;;OAIG;iDACiC,MAAM,KAAG,OAAO;IAIpD;;;;OAIG;wCACwB,MAAM,KAAG,MAAM;IAO1C;;;;;OAKG;6CAEM,MAAM,aACF,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAChC,MAAM;IAOT;;;;OAIG;8CAC8B,MAAM,KAAG,MAAM;IAIhD;;;;OAIG;wCACwB,MAAM,KAAG,MAAM;IAO1C;;;;OAIG;2CAC2B,MAAM,KAAG,MAAM;CAMrC,CAAC"}
@@ -0,0 +1,57 @@
1
+ /**
2
+ * @fileoverview Type Guard Utilities for @plyaz/db package
3
+ *
4
+ * This module provides type guard functions for runtime type checking throughout
5
+ * the @plyaz/db package. These utilities replace direct typeof checks with
6
+ * consistent, reusable type validation functions.
7
+ *
8
+ */
9
+ /**
10
+ * Type guard to check if a value is a string
11
+ *
12
+ * @param {unknown} value - The value to check
13
+ * @returns {value is string} True if value is a string, false otherwise
14
+ *
15
+ * @example
16
+ * ```typescript
17
+ * import { isString } from '@plyaz/db/utils';
18
+ *
19
+ * if (isString(userInput)) {
20
+ * // userInput is now typed as string
21
+ * console.log(userInput.toLowerCase());
22
+ * }
23
+ * ```
24
+ */
25
+ export declare function isString(value: unknown): value is string;
26
+ /**
27
+ * Type guard to check if a value is a non-empty string
28
+ *
29
+ * @param {unknown} value - The value to check
30
+ * @returns {value is string} True if value is a non-empty string, false otherwise
31
+ *
32
+ * @example
33
+ * ```typescript
34
+ * import { isNonEmptyString } from '@plyaz/db/utils';
35
+ *
36
+ * if (isNonEmptyString(tableName)) {
37
+ * // tableName is guaranteed to be a non-empty string
38
+ * const query = `SELECT * FROM ${tableName}`;
39
+ * }
40
+ * ```
41
+ */
42
+ export declare function isNonEmptyString(value: unknown): value is string;
43
+ /**
44
+ * Type guard to check if a value is a number
45
+ *
46
+ * @param {unknown} value - The value to check
47
+ * @returns {value is number} True if value is a number, false otherwise
48
+ */
49
+ export declare function isNumber(value: unknown): value is number;
50
+ /**
51
+ * Type guard to check if a value is an object (not null, not array)
52
+ *
53
+ * @param {unknown} value - The value to check
54
+ * @returns {value is object} True if value is an object, false otherwise
55
+ */
56
+ export declare function isObject(value: unknown): value is object;
57
+ //# sourceMappingURL=typeGuards.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"typeGuards.d.ts","sourceRoot":"","sources":["../../src/utils/typeGuards.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD"}