@happyvertical/utils 0.74.8
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.
- package/AGENT.md +33 -0
- package/LICENSE +7 -0
- package/README.md +143 -0
- package/dist/browser.d.ts +20 -0
- package/dist/browser.d.ts.map +1 -0
- package/dist/browser.js +59 -0
- package/dist/browser.js.map +1 -0
- package/dist/chunks/universal-BeseWxvS.js +934 -0
- package/dist/chunks/universal-BeseWxvS.js.map +1 -0
- package/dist/cli/claude-context.d.ts +3 -0
- package/dist/cli/claude-context.d.ts.map +1 -0
- package/dist/cli/claude-context.js +21 -0
- package/dist/cli/claude-context.js.map +1 -0
- package/dist/cli/index.d.ts +8 -0
- package/dist/cli/index.d.ts.map +1 -0
- package/dist/cli/parse-args.d.ts +61 -0
- package/dist/cli/parse-args.d.ts.map +1 -0
- package/dist/cli/parse-flags.d.ts +22 -0
- package/dist/cli/parse-flags.d.ts.map +1 -0
- package/dist/config/env-config.d.ts +119 -0
- package/dist/config/env-config.d.ts.map +1 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +394 -0
- package/dist/index.js.map +1 -0
- package/dist/shared/code/extraction.d.ts +90 -0
- package/dist/shared/code/extraction.d.ts.map +1 -0
- package/dist/shared/code/index.d.ts +14 -0
- package/dist/shared/code/index.d.ts.map +1 -0
- package/dist/shared/code/sandbox.d.ts +165 -0
- package/dist/shared/code/sandbox.d.ts.map +1 -0
- package/dist/shared/code/validation.d.ts +113 -0
- package/dist/shared/code/validation.d.ts.map +1 -0
- package/dist/shared/index.d.ts +5 -0
- package/dist/shared/index.d.ts.map +1 -0
- package/dist/shared/logger.d.ts +43 -0
- package/dist/shared/logger.d.ts.map +1 -0
- package/dist/shared/types.d.ts +195 -0
- package/dist/shared/types.d.ts.map +1 -0
- package/dist/shared/universal.d.ts +400 -0
- package/dist/shared/universal.d.ts.map +1 -0
- package/dist/web.d.ts +35 -0
- package/dist/web.d.ts.map +1 -0
- package/metadata.json +54 -0
- package/package.json +70 -0
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Sandbox creation and safe code execution utilities
|
|
3
|
+
*
|
|
4
|
+
* Provides secure execution of generated code in isolated VM contexts with
|
|
5
|
+
* controlled globals, timeouts, and resource constraints.
|
|
6
|
+
*/
|
|
7
|
+
import * as vm from 'node:vm';
|
|
8
|
+
/**
|
|
9
|
+
* Options for creating a sandbox execution context
|
|
10
|
+
*/
|
|
11
|
+
export interface SandboxOptions {
|
|
12
|
+
/**
|
|
13
|
+
* Global variables to make available in the sandbox
|
|
14
|
+
* These will be accessible as global variables in the executed code
|
|
15
|
+
*/
|
|
16
|
+
globals?: Record<string, any>;
|
|
17
|
+
/**
|
|
18
|
+
* Maximum execution time in milliseconds
|
|
19
|
+
* Default: 5000ms (5 seconds)
|
|
20
|
+
*/
|
|
21
|
+
timeout?: number;
|
|
22
|
+
/**
|
|
23
|
+
* Allowed built-in JavaScript objects
|
|
24
|
+
* Default: ['Array', 'Object', 'JSON', 'Math', 'Date', 'String', 'Number', 'Boolean', 'RegExp']
|
|
25
|
+
*/
|
|
26
|
+
allowedBuiltins?: string[];
|
|
27
|
+
/**
|
|
28
|
+
* Whether to allow console access (useful for debugging)
|
|
29
|
+
* Default: false (console will be undefined unless provided in globals)
|
|
30
|
+
*/
|
|
31
|
+
allowConsole?: boolean;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Options for executing code in a sandbox
|
|
35
|
+
*/
|
|
36
|
+
export interface ExecuteOptions {
|
|
37
|
+
/**
|
|
38
|
+
* Maximum execution time in milliseconds
|
|
39
|
+
* Overrides the sandbox-level timeout if provided
|
|
40
|
+
*/
|
|
41
|
+
timeout?: number;
|
|
42
|
+
/**
|
|
43
|
+
* Filename to use in error messages and stack traces
|
|
44
|
+
* Default: 'generated-code.js'
|
|
45
|
+
*/
|
|
46
|
+
filename?: string;
|
|
47
|
+
/**
|
|
48
|
+
* Whether to capture and return the last expression value
|
|
49
|
+
* Default: true
|
|
50
|
+
*/
|
|
51
|
+
captureResult?: boolean;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Creates a secure sandbox execution context with controlled globals
|
|
55
|
+
*
|
|
56
|
+
* @param options - Configuration for the sandbox
|
|
57
|
+
* @returns A VM context that can be used with executeCode()
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* ```typescript
|
|
61
|
+
* const sandbox = createSandbox({
|
|
62
|
+
* globals: {
|
|
63
|
+
* cheerio: require('cheerio'),
|
|
64
|
+
* data: { foo: 'bar' }
|
|
65
|
+
* },
|
|
66
|
+
* timeout: 5000,
|
|
67
|
+
* allowedBuiltins: ['Array', 'Object', 'JSON']
|
|
68
|
+
* });
|
|
69
|
+
*
|
|
70
|
+
* const result = executeCode('data.foo', sandbox);
|
|
71
|
+
* // Returns: "bar"
|
|
72
|
+
* ```
|
|
73
|
+
*/
|
|
74
|
+
export declare function createSandbox(options?: SandboxOptions): vm.Context;
|
|
75
|
+
/**
|
|
76
|
+
* Executes code in a sandbox with timeout and error handling
|
|
77
|
+
*
|
|
78
|
+
* @param code - The JavaScript code to execute
|
|
79
|
+
* @param sandbox - The VM context created by createSandbox()
|
|
80
|
+
* @param options - Execution options
|
|
81
|
+
* @returns The result of the code execution
|
|
82
|
+
* @throws {Error} If code execution fails or times out
|
|
83
|
+
*
|
|
84
|
+
* @example
|
|
85
|
+
* ```typescript
|
|
86
|
+
* const sandbox = createSandbox({
|
|
87
|
+
* globals: { x: 10, y: 20 }
|
|
88
|
+
* });
|
|
89
|
+
*
|
|
90
|
+
* const result = executeCode('x + y', sandbox);
|
|
91
|
+
* // Returns: 30
|
|
92
|
+
*
|
|
93
|
+
* // With a function
|
|
94
|
+
* const funcResult = executeCode(`
|
|
95
|
+
* function add(a, b) {
|
|
96
|
+
* return a + b;
|
|
97
|
+
* }
|
|
98
|
+
* add(x, y);
|
|
99
|
+
* `, sandbox);
|
|
100
|
+
* // Returns: 30
|
|
101
|
+
* ```
|
|
102
|
+
*/
|
|
103
|
+
export declare function executeCode<T = any>(code: string, sandbox: vm.Context, options?: ExecuteOptions): T;
|
|
104
|
+
/**
|
|
105
|
+
* Executes async code in a sandbox with timeout and error handling
|
|
106
|
+
*
|
|
107
|
+
* @param code - The JavaScript code to execute (can contain async/await)
|
|
108
|
+
* @param sandbox - The VM context created by createSandbox()
|
|
109
|
+
* @param options - Execution options
|
|
110
|
+
* @returns Promise resolving to the result of the code execution
|
|
111
|
+
* @throws {Error} If code execution fails or times out
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* ```typescript
|
|
115
|
+
* const sandbox = createSandbox({
|
|
116
|
+
* globals: {
|
|
117
|
+
* fetch: require('node-fetch')
|
|
118
|
+
* }
|
|
119
|
+
* });
|
|
120
|
+
*
|
|
121
|
+
* const result = await executeCodeAsync(`
|
|
122
|
+
* const response = await fetch('https://api.example.com/data');
|
|
123
|
+
* const data = await response.json();
|
|
124
|
+
* data;
|
|
125
|
+
* `, sandbox);
|
|
126
|
+
* ```
|
|
127
|
+
*/
|
|
128
|
+
export declare function executeCodeAsync<T = any>(code: string, sandbox: vm.Context, options?: ExecuteOptions): Promise<T>;
|
|
129
|
+
/**
|
|
130
|
+
* Convenience function to create a sandbox and execute code in one step
|
|
131
|
+
*
|
|
132
|
+
* @param code - The JavaScript code to execute
|
|
133
|
+
* @param options - Combined sandbox and execution options
|
|
134
|
+
* @returns The result of the code execution
|
|
135
|
+
*
|
|
136
|
+
* @example
|
|
137
|
+
* ```typescript
|
|
138
|
+
* const result = executeInSandbox('Math.sqrt(16)', {
|
|
139
|
+
* globals: { x: 10 },
|
|
140
|
+
* timeout: 1000
|
|
141
|
+
* });
|
|
142
|
+
* // Returns: 4
|
|
143
|
+
* ```
|
|
144
|
+
*/
|
|
145
|
+
export declare function executeInSandbox<T = any>(code: string, options?: SandboxOptions & ExecuteOptions): T;
|
|
146
|
+
/**
|
|
147
|
+
* Convenience function to create a sandbox and execute async code in one step
|
|
148
|
+
*
|
|
149
|
+
* @param code - The JavaScript code to execute (can contain async/await)
|
|
150
|
+
* @param options - Combined sandbox and execution options
|
|
151
|
+
* @returns Promise resolving to the result of the code execution
|
|
152
|
+
*
|
|
153
|
+
* @example
|
|
154
|
+
* ```typescript
|
|
155
|
+
* const result = await executeInSandboxAsync(`
|
|
156
|
+
* const data = await Promise.resolve({ value: 42 });
|
|
157
|
+
* data.value;
|
|
158
|
+
* `, {
|
|
159
|
+
* timeout: 2000
|
|
160
|
+
* });
|
|
161
|
+
* // Returns: 42
|
|
162
|
+
* ```
|
|
163
|
+
*/
|
|
164
|
+
export declare function executeInSandboxAsync<T = any>(code: string, options?: SandboxOptions & ExecuteOptions): Promise<T>;
|
|
165
|
+
//# sourceMappingURL=sandbox.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/shared/code/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE9B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAuBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,EAAE,CAAC,OAAO,CA2BtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,EACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,EAAE,CAAC,OAAO,EACnB,OAAO,GAAE,cAAmB,GAC3B,CAAC,CAiDH;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAC5C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,EAAE,CAAC,OAAO,EACnB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAmEZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EACtC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAc,GAAG,cAAmB,GAC5C,CAAC,CAGH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,GAAG,GAAG,EACjD,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAc,GAAG,cAAmB,GAC5C,OAAO,CAAC,CAAC,CAAC,CAGZ"}
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Code validation utilities for checking generated code before execution
|
|
3
|
+
*
|
|
4
|
+
* Provides functions to validate code syntax, check for dangerous patterns,
|
|
5
|
+
* and verify code meets security requirements before sandbox execution.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Options for code validation
|
|
9
|
+
*/
|
|
10
|
+
export interface ValidationOptions {
|
|
11
|
+
/**
|
|
12
|
+
* List of allowed global variables
|
|
13
|
+
* If provided, code will be checked for undeclared variables
|
|
14
|
+
*/
|
|
15
|
+
allowedGlobals?: string[];
|
|
16
|
+
/**
|
|
17
|
+
* List of disallowed patterns (regex)
|
|
18
|
+
* Code containing these patterns will fail validation
|
|
19
|
+
*/
|
|
20
|
+
disallowedPatterns?: RegExp[];
|
|
21
|
+
/**
|
|
22
|
+
* Maximum code length in characters
|
|
23
|
+
* Default: 50000
|
|
24
|
+
*/
|
|
25
|
+
maxLength?: number;
|
|
26
|
+
/**
|
|
27
|
+
* Whether to allow require() calls
|
|
28
|
+
* Default: false (dangerous in untrusted code)
|
|
29
|
+
*/
|
|
30
|
+
allowRequire?: boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Whether to allow import statements
|
|
33
|
+
* Default: false (dangerous in untrusted code)
|
|
34
|
+
*/
|
|
35
|
+
allowImport?: boolean;
|
|
36
|
+
/**
|
|
37
|
+
* Whether to allow eval() and Function() constructor
|
|
38
|
+
* Default: false (dangerous in any code)
|
|
39
|
+
*/
|
|
40
|
+
allowEval?: boolean;
|
|
41
|
+
/**
|
|
42
|
+
* Whether to perform syntax check
|
|
43
|
+
* Default: true
|
|
44
|
+
*/
|
|
45
|
+
checkSyntax?: boolean;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Result of code validation
|
|
49
|
+
*/
|
|
50
|
+
export interface ValidationResult {
|
|
51
|
+
/**
|
|
52
|
+
* Whether the code passed all validation checks
|
|
53
|
+
*/
|
|
54
|
+
valid: boolean;
|
|
55
|
+
/**
|
|
56
|
+
* Critical errors that prevent execution
|
|
57
|
+
*/
|
|
58
|
+
errors: string[];
|
|
59
|
+
/**
|
|
60
|
+
* Non-critical warnings about the code
|
|
61
|
+
*/
|
|
62
|
+
warnings: string[];
|
|
63
|
+
/**
|
|
64
|
+
* Statistics about the code
|
|
65
|
+
*/
|
|
66
|
+
stats?: {
|
|
67
|
+
length: number;
|
|
68
|
+
lines: number;
|
|
69
|
+
hasAsync: boolean;
|
|
70
|
+
hasArrowFunctions: boolean;
|
|
71
|
+
hasClasses: boolean;
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Validates code before execution in a sandbox
|
|
76
|
+
*
|
|
77
|
+
* @param code - The code to validate
|
|
78
|
+
* @param options - Validation options
|
|
79
|
+
* @returns Validation result with errors and warnings
|
|
80
|
+
*
|
|
81
|
+
* @example
|
|
82
|
+
* ```typescript
|
|
83
|
+
* const result = validateCode(`
|
|
84
|
+
* function parse(data) {
|
|
85
|
+
* return JSON.parse(data);
|
|
86
|
+
* }
|
|
87
|
+
* `, {
|
|
88
|
+
* allowedGlobals: ['JSON'],
|
|
89
|
+
* maxLength: 10000
|
|
90
|
+
* });
|
|
91
|
+
*
|
|
92
|
+
* if (!result.valid) {
|
|
93
|
+
* console.error('Code validation failed:', result.errors);
|
|
94
|
+
* }
|
|
95
|
+
* ```
|
|
96
|
+
*/
|
|
97
|
+
export declare function validateCode(code: string, options?: ValidationOptions): ValidationResult;
|
|
98
|
+
/**
|
|
99
|
+
* Quick validation to check if code is safe for execution
|
|
100
|
+
* Returns true if code passes basic safety checks
|
|
101
|
+
*
|
|
102
|
+
* @param code - The code to check
|
|
103
|
+
* @returns true if code is safe, false otherwise
|
|
104
|
+
*
|
|
105
|
+
* @example
|
|
106
|
+
* ```typescript
|
|
107
|
+
* if (isSafeCode('return x + y')) {
|
|
108
|
+
* // Safe to execute
|
|
109
|
+
* }
|
|
110
|
+
* ```
|
|
111
|
+
*/
|
|
112
|
+
export declare function isSafeCode(code: string): boolean;
|
|
113
|
+
//# sourceMappingURL=validation.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/shared/code/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,OAAO,CAAC;QAClB,iBAAiB,EAAE,OAAO,CAAC;QAC3B,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAkBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAqGlB;AAqMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOhD"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { Logger } from './types';
|
|
2
|
+
/**
|
|
3
|
+
* Replace the global logger with a custom implementation
|
|
4
|
+
*
|
|
5
|
+
* @param logger - Custom logger implementation
|
|
6
|
+
* @example
|
|
7
|
+
* ```typescript
|
|
8
|
+
* setLogger(new CustomLogger());
|
|
9
|
+
* ```
|
|
10
|
+
*/
|
|
11
|
+
export declare const setLogger: (logger: Logger) => void;
|
|
12
|
+
/**
|
|
13
|
+
* Get the current global logger instance
|
|
14
|
+
*
|
|
15
|
+
* @returns Current logger implementation
|
|
16
|
+
* @example
|
|
17
|
+
* ```typescript
|
|
18
|
+
* const logger = getLogger();
|
|
19
|
+
* logger.info('Application started');
|
|
20
|
+
* ```
|
|
21
|
+
*/
|
|
22
|
+
export declare const getLogger: () => Logger;
|
|
23
|
+
/**
|
|
24
|
+
* Disable all logging by switching to no-op logger
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* ```typescript
|
|
28
|
+
* if (process.env.NODE_ENV === 'production') {
|
|
29
|
+
* disableLogging();
|
|
30
|
+
* }
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
export declare const disableLogging: () => void;
|
|
34
|
+
/**
|
|
35
|
+
* Enable console logging by switching to console logger
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* ```typescript
|
|
39
|
+
* enableLogging(); // Re-enable after disabling
|
|
40
|
+
* ```
|
|
41
|
+
*/
|
|
42
|
+
export declare const enableLogging: () => void;
|
|
43
|
+
//# sourceMappingURL=logger.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/shared/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAwDtC;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,KAAG,IAE1C,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,QAAO,MAE5B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,QAAO,IAEjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,QAAO,IAEhC,CAAC"}
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared type definitions and interfaces for universal use
|
|
3
|
+
*
|
|
4
|
+
* This module provides standardized error classes and logging interfaces
|
|
5
|
+
* used throughout the HAVE SDK. All error classes extend BaseError to
|
|
6
|
+
* provide consistent error handling with context and timestamps.
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Standardized error codes used across the HAVE SDK
|
|
10
|
+
*
|
|
11
|
+
* These codes provide consistent error categorization for better error handling
|
|
12
|
+
* and monitoring across all packages in the SDK.
|
|
13
|
+
*/
|
|
14
|
+
export declare enum ErrorCode {
|
|
15
|
+
/** Input validation failed */
|
|
16
|
+
VALIDATION_ERROR = "VALIDATION_ERROR",
|
|
17
|
+
/** API request/response error */
|
|
18
|
+
API_ERROR = "API_ERROR",
|
|
19
|
+
/** File system operation error */
|
|
20
|
+
FILE_ERROR = "FILE_ERROR",
|
|
21
|
+
/** Network connectivity or HTTP error */
|
|
22
|
+
NETWORK_ERROR = "NETWORK_ERROR",
|
|
23
|
+
/** Database operation error */
|
|
24
|
+
DATABASE_ERROR = "DATABASE_ERROR",
|
|
25
|
+
/** Data parsing or format error */
|
|
26
|
+
PARSING_ERROR = "PARSING_ERROR",
|
|
27
|
+
/** Operation timeout error */
|
|
28
|
+
TIMEOUT_ERROR = "TIMEOUT_ERROR",
|
|
29
|
+
/** Unspecified or unexpected error */
|
|
30
|
+
UNKNOWN_ERROR = "UNKNOWN_ERROR"
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Base error class providing standardized error handling across the HAVE SDK
|
|
34
|
+
*
|
|
35
|
+
* All custom errors extend this class to ensure consistent error structure,
|
|
36
|
+
* context preservation, and debugging capabilities.
|
|
37
|
+
*
|
|
38
|
+
* @example
|
|
39
|
+
* ```typescript
|
|
40
|
+
* throw new BaseError('Something went wrong', ErrorCode.UNKNOWN_ERROR, {
|
|
41
|
+
* userId: 123,
|
|
42
|
+
* operation: 'processData'
|
|
43
|
+
* });
|
|
44
|
+
* ```
|
|
45
|
+
*/
|
|
46
|
+
export declare class BaseError extends Error {
|
|
47
|
+
/** Error classification code */
|
|
48
|
+
readonly code: ErrorCode;
|
|
49
|
+
/** Additional context data for debugging */
|
|
50
|
+
readonly context?: Record<string, unknown>;
|
|
51
|
+
/** When the error occurred */
|
|
52
|
+
readonly timestamp: Date;
|
|
53
|
+
constructor(message: string, code?: ErrorCode, context?: Record<string, unknown>);
|
|
54
|
+
/**
|
|
55
|
+
* Serializes the error to a JSON-compatible object
|
|
56
|
+
* @returns Object containing all error properties
|
|
57
|
+
*/
|
|
58
|
+
toJSON(): {
|
|
59
|
+
name: string;
|
|
60
|
+
message: string;
|
|
61
|
+
code: ErrorCode;
|
|
62
|
+
context: Record<string, unknown> | undefined;
|
|
63
|
+
timestamp: string;
|
|
64
|
+
stack: string | undefined;
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Error thrown when input validation fails
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```typescript
|
|
72
|
+
* throw new ValidationError('Email format invalid', {
|
|
73
|
+
* email: 'invalid-email',
|
|
74
|
+
* field: 'userEmail'
|
|
75
|
+
* });
|
|
76
|
+
* ```
|
|
77
|
+
*/
|
|
78
|
+
export declare class ValidationError extends BaseError {
|
|
79
|
+
constructor(message: string, context?: Record<string, unknown>);
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Error thrown for API-related failures
|
|
83
|
+
*
|
|
84
|
+
* @example
|
|
85
|
+
* ```typescript
|
|
86
|
+
* throw new ApiError('HTTP 404 Not Found', {
|
|
87
|
+
* url: 'https://api.example.com/users/123',
|
|
88
|
+
* status: 404
|
|
89
|
+
* });
|
|
90
|
+
* ```
|
|
91
|
+
*/
|
|
92
|
+
export declare class ApiError extends BaseError {
|
|
93
|
+
constructor(message: string, context?: Record<string, unknown>);
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Error thrown for file system operation failures
|
|
97
|
+
*
|
|
98
|
+
* @example
|
|
99
|
+
* ```typescript
|
|
100
|
+
* throw new FileError('File not found', {
|
|
101
|
+
* path: '/path/to/missing/file.txt',
|
|
102
|
+
* operation: 'read'
|
|
103
|
+
* });
|
|
104
|
+
* ```
|
|
105
|
+
*/
|
|
106
|
+
export declare class FileError extends BaseError {
|
|
107
|
+
constructor(message: string, context?: Record<string, unknown>);
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Error thrown for network connectivity or HTTP failures
|
|
111
|
+
*
|
|
112
|
+
* @example
|
|
113
|
+
* ```typescript
|
|
114
|
+
* throw new NetworkError('Connection timeout', {
|
|
115
|
+
* host: 'example.com',
|
|
116
|
+
* timeout: 5000,
|
|
117
|
+
* attempt: 3
|
|
118
|
+
* });
|
|
119
|
+
* ```
|
|
120
|
+
*/
|
|
121
|
+
export declare class NetworkError extends BaseError {
|
|
122
|
+
constructor(message: string, context?: Record<string, unknown>);
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Error thrown for database operation failures
|
|
126
|
+
*
|
|
127
|
+
* @example
|
|
128
|
+
* ```typescript
|
|
129
|
+
* throw new DatabaseError('Connection failed', {
|
|
130
|
+
* database: 'production',
|
|
131
|
+
* query: 'SELECT * FROM users',
|
|
132
|
+
* errorCode: 'ECONNREFUSED'
|
|
133
|
+
* });
|
|
134
|
+
* ```
|
|
135
|
+
*/
|
|
136
|
+
export declare class DatabaseError extends BaseError {
|
|
137
|
+
constructor(message: string, context?: Record<string, unknown>);
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Error thrown for data parsing or format failures
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* ```typescript
|
|
144
|
+
* throw new ParsingError('Invalid JSON format', {
|
|
145
|
+
* input: '{invalid json}',
|
|
146
|
+
* parser: 'JSON.parse',
|
|
147
|
+
* position: 1
|
|
148
|
+
* });
|
|
149
|
+
* ```
|
|
150
|
+
*/
|
|
151
|
+
export declare class ParsingError extends BaseError {
|
|
152
|
+
constructor(message: string, context?: Record<string, unknown>);
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Error thrown when operations exceed their timeout duration
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* ```typescript
|
|
159
|
+
* throw new TimeoutError('Operation timed out', {
|
|
160
|
+
* timeout: 5000,
|
|
161
|
+
* operation: 'fetchData',
|
|
162
|
+
* elapsedTime: 5234
|
|
163
|
+
* });
|
|
164
|
+
* ```
|
|
165
|
+
*/
|
|
166
|
+
export declare class TimeoutError extends BaseError {
|
|
167
|
+
constructor(message: string, context?: Record<string, unknown>);
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Logging interface for consistent logging across the HAVE SDK
|
|
171
|
+
*
|
|
172
|
+
* All logging implementations should follow this interface to ensure
|
|
173
|
+
* consistent behavior and easy swapping of logging backends.
|
|
174
|
+
*
|
|
175
|
+
* @example
|
|
176
|
+
* ```typescript
|
|
177
|
+
* class CustomLogger implements Logger {
|
|
178
|
+
* info(message: string, context?: Record<string, unknown>) {
|
|
179
|
+
* console.log(`INFO: ${message}`, context);
|
|
180
|
+
* }
|
|
181
|
+
* // ... implement other methods
|
|
182
|
+
* }
|
|
183
|
+
* ```
|
|
184
|
+
*/
|
|
185
|
+
export interface Logger {
|
|
186
|
+
/** Log debug information (lowest priority) */
|
|
187
|
+
debug(message: string, context?: Record<string, unknown>): void;
|
|
188
|
+
/** Log informational messages */
|
|
189
|
+
info(message: string, context?: Record<string, unknown>): void;
|
|
190
|
+
/** Log warning messages */
|
|
191
|
+
warn(message: string, context?: Record<string, unknown>): void;
|
|
192
|
+
/** Log error messages (highest priority) */
|
|
193
|
+
error(message: string, context?: Record<string, unknown>): void;
|
|
194
|
+
}
|
|
195
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,oBAAY,SAAS;IACnB,8BAA8B;IAC9B,gBAAgB,qBAAqB;IACrC,iCAAiC;IACjC,SAAS,cAAc;IACvB,kCAAkC;IAClC,UAAU,eAAe;IACzB,yCAAyC;IACzC,aAAa,kBAAkB;IAC/B,+BAA+B;IAC/B,cAAc,mBAAmB;IACjC,mCAAmC;IACnC,aAAa,kBAAkB;IAC/B,8BAA8B;IAC9B,aAAa,kBAAkB;IAC/B,sCAAsC;IACtC,aAAa,kBAAkB;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,gCAAgC;IAChC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,4CAA4C;IAC5C,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,8BAA8B;IAC9B,SAAgB,SAAS,EAAE,IAAI,CAAC;gBAG9B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,SAAmC,EACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUnC;;;OAGG;IACH,MAAM;;;;;;;;CAUP;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,SAAS;gBACzB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,SAAU,SAAQ,SAAS;gBAC1B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,MAAM;IACrB,8CAA8C;IAC9C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,iCAAiC;IACjC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,2BAA2B;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,4CAA4C;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACjE"}
|