You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Exception.md
+31-31Lines changed: 31 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Exception
2
2
3
-
Enhanced error handling with expressive error reporting and stack trace support.
3
+
Enhanced error handling with expressive error reporting and stack trace support. Provides better error information than standard JavaScript errors with template-based error messages, validation error aggregation, enhanced stack trace parsing, and HTTP status code integration.
The following methods can be accessed directly from Exception itself.
16
+
The following methods can be accessed directly from Exception itself. These factory methods provide convenient ways to create Exception instances for common error scenarios without needing to instantiate the class directly.
17
17
18
-
### Creating Exceptions with Templates
18
+
### 1.1. Creating Exceptions with Templates
19
19
20
-
The following example shows how to create exceptions with template strings.
20
+
The following example shows how to create exceptions with template strings using placeholder substitution.
21
21
22
22
```typescript
23
23
throwException.for('Something %s is %s', 'good', 'bad');
A new Exception instance configured from the response object.
61
61
62
-
### Creating Exceptions for Validation Errors
62
+
### 1.3. Creating Exceptions for Validation Errors
63
63
64
-
The following example shows how to create exceptions for validation errors.
64
+
The following example shows how to create exceptions specifically for validation errors with field-specific error messages.
65
65
66
66
```typescript
67
67
throwException.forErrors({
@@ -80,9 +80,9 @@ throw Exception.forErrors({
80
80
81
81
A new Exception instance with "Invalid Parameters" message and error details.
82
82
83
-
### Requiring Conditions
83
+
### 1.4. Requiring Conditions
84
84
85
-
The following example shows how to assert conditions and throw if they fail.
85
+
The following example shows how to assert conditions and throw exceptions if they fail.
86
86
87
87
```typescript
88
88
Exception.require(count>0, 'Count %s must be positive', count);
@@ -100,9 +100,9 @@ Exception.require(count > 0, 'Count %s must be positive', count);
100
100
101
101
Void if condition is true, throws Exception if false.
102
102
103
-
### Try-Catch Wrapper
103
+
### 1.5. Try-Catch Wrapper
104
104
105
-
The following example shows how to use the synchronous try-catch wrapper.
105
+
The following example shows how to use the synchronous try-catch wrapper for safe operation execution.
106
106
107
107
```typescript
108
108
const result =Exception
@@ -123,9 +123,9 @@ const result = Exception
123
123
124
124
An object with a `catch` method for handling errors.
125
125
126
-
### Upgrading Errors
126
+
### 1.6. Upgrading Errors
127
127
128
-
The following example shows how to upgrade regular errors to exceptions.
128
+
The following example shows how to upgrade regular errors to exceptions with additional context.
129
129
130
130
```typescript
131
131
try {
@@ -146,9 +146,9 @@ try {
146
146
147
147
An Exception instance (returns original if already an Exception).
148
148
149
-
## Properties
149
+
## 2. Properties
150
150
151
-
The following properties are available when instantiating an Exception.
151
+
The following properties are available when instantiating an Exception. These properties provide access to error details, HTTP status codes, and position information for debugging purposes.
152
152
153
153
| Property | Type | Description |
154
154
|----------|------|-------------|
@@ -158,13 +158,13 @@ The following properties are available when instantiating an Exception.
158
158
|`start`|`number`| Starting character position of the error |
159
159
|`type`|`string`| Exception type name |
160
160
161
-
## Methods
161
+
## 3. Methods
162
162
163
-
The following methods are available when instantiating an Exception.
163
+
The following methods are available when instantiating an Exception. These methods allow you to configure the exception with additional context and convert it to various formats for different use cases.
164
164
165
-
### Setting Error Code
165
+
### 3.1. Setting Error Code
166
166
167
-
The following example shows how to set the HTTP status code.
167
+
The following example shows how to set the HTTP status code for the exception.
168
168
169
169
```typescript
170
170
exception.withCode(404);
@@ -180,9 +180,9 @@ exception.withCode(404);
180
180
181
181
The Exception instance to allow method chaining.
182
182
183
-
### Adding Validation Errors
183
+
### 3.2. Adding Validation Errors
184
184
185
-
The following example shows how to add validation errors.
185
+
The following example shows how to add validation errors with field-specific error messages.
186
186
187
187
```typescript
188
188
exception.withErrors({
@@ -201,9 +201,9 @@ exception.withErrors({
201
201
202
202
The Exception instance to allow method chaining.
203
203
204
-
### Setting Position Information
204
+
### 3.3. Setting Position Information
205
205
206
-
The following example shows how to set character position information.
206
+
The following example shows how to set character position information for parsing errors.
Copy file name to clipboardExpand all lines: docs/Queues.md
+54-48Lines changed: 54 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,25 +1,21 @@
1
-
# Queue
1
+
# Queues
2
2
3
-
Priority-based queue implementations for managing items and tasks with FIFO ordering.
3
+
Priority-based queue implementations for managing items and tasks with FIFO ordering. Includes both generic item queues and specialized task queues with priority-based ordering, FIFO ordering within same priority levels, task execution with before/after hooks, and chainable API for queue operations.
4
4
5
-
When an event is triggered, Stackpress doesn’t just fire off listeners blindly. Instead, it organizes them into a `TaskQueue`, which then consumes items sequentially by priority.
5
+
When an event is triggered, Stackpress doesn't just fire off listeners blindly. Instead, it organizes them into a `TaskQueue`, which then consumes items sequentially by priority. Because events can be defined anywhere, event priority allows you to structure execution like a series of steps—making the flow of your application predictable and easy to follow.
6
6
7
-
Because events can be defined anywhere, event priority allows you to structure execution like a series of steps—making the flow of your application predictable and easy to follow.
8
-
9
-
Even better, the `TaskQueue` makes the `EventEmitter` a true **plugin system**: you can insert new code between existing listeners without rewriting or restructuring what’s already there. This means features, extensions, or third-party modules can seamlessly “hook into” the event pipeline without breaking your core logic.
Even better, the `TaskQueue` makes the `EventEmitter` a true **plugin system**: you can insert new code between existing listeners without rewriting or restructuring what's already there. This means features, extensions, or third-party modules can seamlessly "hook into" the event pipeline without breaking your core logic.
12
8
13
9
```typescript
14
10
const itemQueue =newItemQueue<string>();
15
11
const taskQueue =newTaskQueue<[number]>();
16
12
```
17
13
18
-
## ItemQueue
14
+
## 1. ItemQueue
19
15
20
-
An item queue that orders and consumes items sequentially based on priority (FIFO by default).
16
+
An item queue that orders and consumes items sequentially based on priority with FIFO ordering by default. The ItemQueue provides the foundation for priority-based processing where items with higher priority values are processed before items with lower priority values.
21
17
22
-
### Properties
18
+
### 1.1. Properties
23
19
24
20
The following properties are available when instantiating an ItemQueue.
25
21
@@ -28,13 +24,9 @@ The following properties are available when instantiating an ItemQueue.
28
24
|`queue`|`Item<I>[]`| The internal queue array (readonly) |
29
25
|`size`|`number`| The number of items in the queue |
30
26
31
-
### Methods
32
-
33
-
The following methods are available when instantiating an ItemQueue.
34
-
35
-
#### Adding Items with Priority
27
+
### 1.2. Adding Items with Priority
36
28
37
-
The following example shows how to add items with specific priority levels.
29
+
The following example shows how to add items with specific priority levels for controlled execution order.
38
30
39
31
```typescript
40
32
const queue =newItemQueue<string>();
@@ -54,9 +46,9 @@ queue.add('low', 1);
54
46
55
47
The ItemQueue instance to allow method chaining.
56
48
57
-
####Adding Items to Bottom
49
+
###1.3. Adding Items to Bottom
58
50
59
-
The following example shows how to add items to the bottom of the queue (lowest priority).
51
+
The following example shows how to add items to the bottom of the queue with the lowest priority.
60
52
61
53
```typescript
62
54
queue.push('bottom-item');
@@ -72,9 +64,9 @@ queue.push('bottom-item');
72
64
73
65
The ItemQueue instance to allow method chaining.
74
66
75
-
####Adding Items to Top
67
+
###1.4. Adding Items to Top
76
68
77
-
The following example shows how to add items to the top of the queue (highest priority).
69
+
The following example shows how to add items to the top of the queue with the highest priority.
78
70
79
71
```typescript
80
72
queue.shift('top-item');
@@ -90,7 +82,7 @@ queue.shift('top-item');
90
82
91
83
The ItemQueue instance to allow method chaining.
92
84
93
-
####Consuming Items
85
+
###1.5. Consuming Items
94
86
95
87
The following example shows how to consume items one at a time in priority order.
The next item in the queue, or `undefined` if the queue is empty.
105
97
106
-
## TaskQueue
98
+
## 2. TaskQueue
107
99
108
-
A task queue that extends ItemQueue specifically for executing functions sequentially.
100
+
A task queue that extends ItemQueue specifically for executing functions sequentially with priority-based ordering. The TaskQueue provides advanced features like before/after hooks, execution control, and status reporting for complex task management scenarios.
For hooks: `false` to abort execution, any other value to continue.
242
230
243
-
### Task Execution Flow
231
+
## 3. Task Execution Flow
232
+
233
+
The following describes the sequential execution flow when running tasks in a TaskQueue. Understanding this flow is essential for implementing proper error handling and execution control in your applications.
234
+
235
+
### 3.1. Execution Steps
236
+
237
+
The task execution follows a predictable sequence that allows for monitoring and control at each stage.
238
+
239
+
1.**Before Hook** — Called before each task (if set)
240
+
2.**Task Execution** — The actual task function is called
241
+
3.**After Hook** — Called after each task (if set)
242
+
243
+
### 3.2. Execution Control
244
+
245
+
If any step returns `false`, execution is aborted and the queue returns `Status.ABORT`. This provides fine-grained control over task execution flow.
246
+
247
+
-**Continue Execution** — Return `true` or any truthy value
248
+
-**Abort Execution** — Return `false` to stop processing remaining tasks
249
+
250
+
## 4. Status Codes
251
+
252
+
The following status codes are returned by TaskQueue operations to indicate the result of task execution. These codes follow HTTP status code conventions for consistency across the Stackpress ecosystem.
244
253
245
-
1.**Before Hook**: Called before each task (if set)
246
-
2.**Task Execution**: The actual task function is called
247
-
3.**After Hook**: Called after each task (if set)
254
+
### 4.1. Success Codes
248
255
249
-
If any step returns `false`, execution is aborted and the queue returns `Status.ABORT`.
256
+
-**Status.OK (200)** — All tasks completed successfully
257
+
-**Status.NOT_FOUND (404)** — No tasks in the queue
250
258
251
-
### Status Codes
259
+
### 4.2. Error Codes
252
260
253
-
-`Status.OK` (200): All tasks completed successfully
254
-
-`Status.ABORT` (309): Execution was aborted by a task or hook
255
-
-`Status.NOT_FOUND` (404): No tasks in the queue
261
+
-**Status.ABORT (309)** — Execution was aborted by a task or hook
0 commit comments