@prozilla-os/shared 1.3.0 → 1.4.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.
package/README.md CHANGED
@@ -4,9 +4,9 @@
4
4
  <a href="https://os.prozilla.dev/"><img src="https://os.prozilla.dev/assets/logo.svg?v=2" height="200" alt="ProzillaOS" /></a>
5
5
  </p>
6
6
  <p>
7
- <a href="https://github.com/prozilla-os/ProzillaOS/blob/main/LICENSE.md"><img alt="License" src="https://img.shields.io/github/license/Prozilla/ProzillaOS?style=flat-square&color=FF4D5B&label=License"></a>
8
- <a href="https://github.com/prozilla-os/ProzillaOS"><img alt="Stars" src="https://img.shields.io/github/stars/Prozilla/ProzillaOS?style=flat-square&color=FED24C&label=%E2%AD%90"></a>
9
- <a href="https://github.com/prozilla-os/ProzillaOS"><img alt="Forks" src="https://img.shields.io/github/forks/Prozilla/ProzillaOS?style=flat-square&color=4D9CFF&label=Forks&logo=github"></a>
7
+ <a href="https://github.com/prozilla-os/ProzillaOS/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/prozilla-os/ProzillaOS?style=flat-square&color=FF4D5B&label=License"></a>
8
+ <a href="https://github.com/prozilla-os/ProzillaOS"><img alt="Stars" src="https://img.shields.io/github/stars/prozilla-os/ProzillaOS?style=flat-square&color=FED24C&label=%E2%AD%90"></a>
9
+ <a href="https://github.com/prozilla-os/ProzillaOS"><img alt="Forks" src="https://img.shields.io/github/forks/prozilla-os/ProzillaOS?style=flat-square&color=4D9CFF&label=Forks&logo=github"></a>
10
10
  <a href="https://www.npmjs.com/package/prozilla-os"><img alt="NPM Version" src="https://img.shields.io/npm/v/prozilla-os?logo=npm&style=flat-square&label=prozilla-os&color=FF4D5B"></a>
11
11
  </p>
12
12
  </div>
package/dist/main.d.ts CHANGED
@@ -7,47 +7,112 @@ export declare const ANSI: {
7
7
  /**
8
8
  * Foreground colors.
9
9
  */
10
- fg: {
11
- black: string;
12
- red: string;
13
- green: string;
14
- yellow: string;
15
- blue: string;
16
- magenta: string;
17
- cyan: string;
18
- white: string;
10
+ readonly fg: {
11
+ readonly black: "\u001B[30m";
12
+ readonly red: "\u001B[31m";
13
+ readonly green: "\u001B[32m";
14
+ readonly yellow: "\u001B[33m";
15
+ readonly blue: "\u001B[34m";
16
+ readonly magenta: "\u001B[35m";
17
+ readonly cyan: "\u001B[36m";
18
+ readonly white: "\u001B[37m";
19
19
  };
20
20
  /**
21
21
  * Background colors.
22
22
  */
23
- bg: {
24
- black: string;
25
- red: string;
26
- green: string;
27
- yellow: string;
28
- blue: string;
29
- magenta: string;
30
- cyan: string;
31
- white: string;
23
+ readonly bg: {
24
+ readonly black: "\u001B[40m";
25
+ readonly red: "\u001B[41m";
26
+ readonly green: "\u001B[42m";
27
+ readonly yellow: "\u001B[43m";
28
+ readonly blue: "\u001B[44m";
29
+ readonly magenta: "\u001B[45m";
30
+ readonly cyan: "\u001B[46m";
31
+ readonly white: "\u001B[47m";
32
32
  };
33
33
  /**
34
34
  * Screen buffer and clearing controls.
35
35
  */
36
- screen: {
37
- enterAltBuffer: string;
38
- exitAltBuffer: string;
39
- clear: string;
40
- home: string;
36
+ readonly screen: {
37
+ readonly enterAltBuffer: "\u001B[?1049h";
38
+ readonly exitAltBuffer: "\u001B[?1049l";
39
+ readonly clear: "\u001B[2J";
40
+ readonly clearLine: "\u001B[2K";
41
+ readonly home: "\u001B[H";
42
+ };
43
+ /**
44
+ * Cursor controls.
45
+ */
46
+ readonly cursor: {
47
+ /** Changes the position of the cursor. */
48
+ readonly position: (row: number, column: number) => string;
49
+ readonly hide: "\u001B[?25l";
50
+ readonly show: "\u001B[?25h";
51
+ readonly save: "\u001B[s";
52
+ readonly restore: "\u001B[u";
53
+ };
54
+ /**
55
+ * Terminal input.
56
+ */
57
+ readonly input: {
58
+ /** Move cursor up. */
59
+ readonly arrowUp: "\u001B[A";
60
+ /** Move cursor down. */
61
+ readonly arrowDown: "\u001B[B";
62
+ /** Move cursor right. */
63
+ readonly arrowRight: "\u001B[C";
64
+ /** Move cursor left. */
65
+ readonly arrowLeft: "\u001B[D";
66
+ readonly horizontalTab: "\t";
67
+ readonly lineFeed: "\n";
68
+ readonly verticalTab: "\v";
69
+ readonly formFeed: "\f";
70
+ readonly carriageReturn: "\r";
71
+ readonly backspace: "\b";
72
+ readonly delete: "";
73
+ readonly escape: "\u001B";
74
+ readonly pageUp: "\u001B[5~";
75
+ readonly pageDown: "\u001B[6~";
76
+ readonly ctrlA: "\u0001";
77
+ readonly ctrlB: "\u0002";
78
+ readonly ctrlC: "\u0003";
79
+ readonly ctrlD: "\u0004";
80
+ readonly ctrlE: "\u0005";
81
+ readonly ctrlF: "\u0006";
82
+ readonly ctrlG: "\u0007";
83
+ readonly ctrlH: "\b";
84
+ readonly ctrlI: "\t";
85
+ readonly ctrlJ: "\n";
86
+ readonly ctrlK: "\v";
87
+ readonly ctrlL: "\f";
88
+ readonly ctrlM: "\r";
89
+ readonly ctrlN: "\u000E";
90
+ readonly ctrlO: "\u000F";
91
+ readonly ctrlP: "\u0010";
92
+ readonly ctrlQ: "\u0011";
93
+ readonly ctrlR: "\u0012";
94
+ readonly ctrlS: "\u0013";
95
+ readonly ctrlT: "\u0014";
96
+ readonly ctrlU: "\u0015";
97
+ readonly ctrlV: "\u0016";
98
+ readonly ctrlW: "\u0017";
99
+ readonly ctrlX: "\u0018";
100
+ readonly ctrlY: "\u0019";
101
+ readonly ctrlZ: "\u001A";
41
102
  };
42
103
  /**
43
104
  * Decorations.
44
105
  */
45
- decoration: {
46
- dim: string;
47
- bold: string;
48
- underline: string;
106
+ readonly decoration: {
107
+ readonly dim: "\u001B[2m";
108
+ readonly bold: "\u001B[1m";
109
+ readonly italic: "\u001B[3m";
110
+ readonly underline: "\u001B[4m";
111
+ readonly blink: "\u001B[5m";
112
+ readonly invert: "\u001B[7m";
113
+ readonly strike: "\u001B[9m";
49
114
  };
50
- reset: string;
115
+ readonly reset: "\u001B[0m";
51
116
  };
52
117
 
53
118
  /**
@@ -90,6 +155,38 @@ export declare class Ansi {
90
155
  * Makes text white using {@link ANSI.fg.white}.
91
156
  */
92
157
  static white(text: string): string;
158
+ /**
159
+ * Sets background to black using {@link ANSI.bg.black}.
160
+ */
161
+ static blackBackground(text: string): string;
162
+ /**
163
+ * Sets background to red using {@link ANSI.bg.red}.
164
+ */
165
+ static redBackground(text: string): string;
166
+ /**
167
+ * Sets background to green using {@link ANSI.bg.green}.
168
+ */
169
+ static greenBackground(text: string): string;
170
+ /**
171
+ * Sets background to yellow using {@link ANSI.bg.yellow}.
172
+ */
173
+ static yellowBackground(text: string): string;
174
+ /**
175
+ * Sets background to blue using {@link ANSI.bg.blue}.
176
+ */
177
+ static blueBackground(text: string): string;
178
+ /**
179
+ * Sets background to magenta using {@link ANSI.bg.magenta}.
180
+ */
181
+ static magentaBackground(text: string): string;
182
+ /**
183
+ * Sets background to cyan using {@link ANSI.bg.cyan}.
184
+ */
185
+ static cyanBackground(text: string): string;
186
+ /**
187
+ * Sets background to white using {@link ANSI.bg.white}.
188
+ */
189
+ static whiteBackground(text: string): string;
93
190
  /**
94
191
  * Makes text bold using {@link ANSI.decoration.bold}.
95
192
  */
@@ -98,6 +195,22 @@ export declare class Ansi {
98
195
  * Makes text dim using {@link ANSI.decoration.dim}.
99
196
  */
100
197
  static dim(text: string): string;
198
+ /**
199
+ * Makes text italic using {@link ANSI.decoration.italic}.
200
+ */
201
+ static italic(text: string): string;
202
+ /**
203
+ * Underlines text using {@link ANSI.decoration.underline}.
204
+ */
205
+ static underline(text: string): string;
206
+ /**
207
+ * Inverts foreground and background colors using {@link ANSI.decoration.invert}.
208
+ */
209
+ static invert(text: string): string;
210
+ /**
211
+ * Makes text strike through using {@link ANSI.decoration.strike}.
212
+ */
213
+ static strike(text: string): string;
101
214
  /**
102
215
  * Removes all ANSI escape sequences.
103
216
  */
@@ -108,12 +221,60 @@ export declare class Ansi {
108
221
  static stripColors(text: string): string;
109
222
  }
110
223
 
111
- /**
112
- * A function that handles an event asynchronously.
113
- * @typeParam T - A record of all events.
114
- * @typeParam K - The event this function handles.
115
- */
116
- export declare type AsyncListener<T extends Record<keyof T, unknown[]>, K extends keyof T> = (...args: T[K]) => Promise<void>;
224
+ export declare abstract class BaseResult<V, E> {
225
+ /**
226
+ * Returns `true` if this result is a {@link Result.Success}.
227
+ */
228
+ isOk(): this is Result.Success<V, E>;
229
+ /**
230
+ * Returns `true` if this result is a {@link Result.Failure}.
231
+ */
232
+ isError(): this is Result.Failure<V, E>;
233
+ /**
234
+ * Transforms the value of this result using the provided callback if this is a {@link Result.Success}.
235
+ * Does nothing if this result is a {@link Result.Failure}.
236
+ */
237
+ abstract map<W>(callback: (value: V) => W): Result<W, E>;
238
+ /**
239
+ * Transforms the error of this result using the provided callback if this is a {@link Result.Failure}.
240
+ * Does nothing if this result is a {@link Result.Success}.
241
+ */
242
+ abstract mapError<F>(callback: (error: E) => F): Result<V, F>;
243
+ /**
244
+ * Chains a new {@link Result}-returning operation to this result if this is a {@link Result.Success}.
245
+ * Does nothing if this result is a {@link Result.Failure}.
246
+ */
247
+ abstract next<W, F>(callback: (value: V) => Result<W, F>): Result<W, E | F>;
248
+ /**
249
+ * Provides a recovery path for this result if this is a {@link Result.Failure} by returning a new {@link Result}.
250
+ * Does nothing if this result is a {@link Result.Success}.
251
+ */
252
+ abstract orElse<W, F>(callback: (error: E) => Result<W, F>): Result<V | W, F | E>;
253
+ /**
254
+ * Returns the {@link Result.Success} value of this instance or the provided default value if this is a {@link Result.Failure}.
255
+ */
256
+ abstract unwrapOr<W>(defaultValue: W): V | W;
257
+ /**
258
+ * Executes the `ok` callback if this is a {@link Result.Success}, or the `error` callback
259
+ * if this is a {@link Result.Failure}, returning the result.
260
+ */
261
+ abstract match<A, B>(ok: (value: V) => A, error: (error: E) => B): A | B;
262
+ /**
263
+ * Executes a callback for side effects if this result is a {@link Result.Success}.
264
+ */
265
+ ifOk(callback: (value: V) => void): this;
266
+ /**
267
+ * Executes a callback for side effects if this result is a {@link Result.Failure}.
268
+ */
269
+ ifError(callback: (error: E) => void): this;
270
+ /**
271
+ * Validates the value of this result against a predicate.
272
+ * Converts to {@link Result.Failure} if the predicate returns `false`.
273
+ * Does nothing if this result is already a {@link Result.Failure}.
274
+ */
275
+ abstract filter<U extends V, F>(predicate: (value: V) => value is U, createError: (value: V) => F): Result<U, E | F>;
276
+ abstract filter<F>(predicate: (value: V) => boolean, createError: (value: V) => F): Result<V, E | F>;
277
+ }
117
278
 
118
279
  declare function bold(text: string): string;
119
280
 
@@ -150,13 +311,6 @@ export declare class EventEmitter<T extends Record<keyof T, unknown[]>> {
150
311
  * @returns The wrapped listener.
151
312
  */
152
313
  once<K extends keyof T>(event: K, listener: Listener<T, K>): Listener<T, K>;
153
- /**
154
- * Starts listening to an event.
155
- * @param event - The event to listen to.
156
- * @param listener - The function to call when the event is emitted.
157
- * @returns The wrapped listener.
158
- */
159
- onAsync<K extends keyof T>(event: K, listener: AsyncListener<T, K>, onRejected?: Parameters<Promise<void>["catch"]>[0]): Listener<T, K>;
160
314
  /**
161
315
  * Removes an event listener.
162
316
  * @param event - The event to remove the listener from.
@@ -169,6 +323,12 @@ export declare class EventEmitter<T extends Record<keyof T, unknown[]>> {
169
323
  * @param args - The arguments to pass to the listeners.
170
324
  */
171
325
  emit<K extends keyof T>(event: K, ...args: T[K]): void;
326
+ /**
327
+ * Emits an event and waits for all listeners to resolve.
328
+ * @param event - The event to emit.
329
+ * @param args - The arguments to pass to the listeners.
330
+ */
331
+ emitAsync<K extends keyof T>(event: K, ...args: T[K]): Promise<void>;
172
332
  }
173
333
 
174
334
  /**
@@ -223,6 +383,11 @@ export declare function isValidNumber(input: number | string): boolean;
223
383
 
224
384
  declare function italic(text: string): string;
225
385
 
386
+ /**
387
+ * Converts a kebab-case string to camelCase.
388
+ */
389
+ export declare function kebabToCamelCase(value: string): string;
390
+
226
391
  declare function link(label: string, url: string): string;
227
392
 
228
393
  /**
@@ -230,7 +395,7 @@ declare function link(label: string, url: string): string;
230
395
  * @typeParam T - A record of all events.
231
396
  * @typeParam K - The event this function handles.
232
397
  */
233
- export declare type Listener<T extends Record<keyof T, unknown[]>, K extends keyof T> = (...args: T[K]) => void;
398
+ export declare type Listener<T extends Record<keyof T, unknown[]>, K extends keyof T> = (...args: T[K]) => void | Promise<void>;
234
399
 
235
400
  /**
236
401
  * A simple wrapper for {@link console} that logs formatted text and supports log levels.
@@ -278,6 +443,10 @@ export declare class Logger {
278
443
  prefix: {
279
444
  [key in LogLevel | "global"]?: string;
280
445
  };
446
+ get errorCount(): number;
447
+ set errorCount(value: number);
448
+ get warningCount(): number;
449
+ set warningCount(value: number);
281
450
  constructor(options?: {
282
451
  /** {@inheritDoc Logger.level}. */
283
452
  level?: Logger["level"];
@@ -538,6 +707,99 @@ export declare function removeDuplicatesFromArray<Type>(array: Type[]): Type[];
538
707
  */
539
708
  export declare function removeFromArray<Type>(item: Type, array: Type[]): void;
540
709
 
710
+ /**
711
+ * Represents either a success or a failure.
712
+ *
713
+ * Can be used as the return value of a function instead of throwing errors.
714
+ * This improves type-safety and helps you control the flow of your function.
715
+ *
716
+ * This is inspired by [neverthrow by supermacro](https://github.com/supermacro/neverthrow).
717
+ *
718
+ * A success can be created using {@link Result.ok} and a failure using {@link Result.error}.
719
+ */
720
+ export declare type Result<T, E> = Result.Success<T, E> | Result.Failure<T, E>;
721
+
722
+ export declare namespace Result {
723
+ /**
724
+ * Represents the result of a successful operation.
725
+ */
726
+ export class Success<V, E> extends BaseResult<V, E> {
727
+ readonly value: V;
728
+ constructor(value: V);
729
+ isOk(): this is Success<V, E>;
730
+ map<W>(callback: (value: V) => W): Result<W, E>;
731
+ mapError<F>(_callback: (error: E) => F): Result<V, F>;
732
+ next<W, F>(callback: (value: V) => Result<W, F>): Result<W, E | F>;
733
+ orElse<W, F>(_callback: (error: E) => Result<W, F>): Result<V, E>;
734
+ unwrapOr<W>(_defaultValue: W): V;
735
+ match<A, B>(ok: (value: V) => A, _error: (error: E) => B): A;
736
+ filter<U extends V, F>(predicate: (value: V) => value is U, createError: (value: V) => F): Result<U, E | F>;
737
+ filter<F>(predicate: (value: V) => boolean, createError: (value: V) => F): Result<V, E | F>;
738
+ }
739
+ /**
740
+ * Represents the result of a failed operation.
741
+ */
742
+ export class Failure<V, E> extends BaseResult<V, E> {
743
+ readonly error: E;
744
+ constructor(error: E);
745
+ isError(): this is Failure<V, E>;
746
+ map<W>(_callback: (value: V) => W): Result<W, E>;
747
+ mapError<F>(callback: (error: E) => F): Result<V, F>;
748
+ next<W, F>(_callback: (value: V) => Result<W, F>): Failure<W, E>;
749
+ orElse<W, F>(callback: (error: E) => Result<W, F>): Result<W, F>;
750
+ unwrapOr<W>(defaultValue: W): W;
751
+ match<A, B>(_ok: (value: V) => A, error: (error: E) => B): B;
752
+ filter<U extends V, F>(predicate: (value: V) => value is U, createError: (value: V) => F): Result<U, E | F>;
753
+ filter<F>(predicate: (value: V) => boolean, createError: (value: V) => F): Result<V, E | F>;
754
+ }
755
+ /**
756
+ * Creates a {@link Result.Success} instance.
757
+ */
758
+ export function ok<T, E = never>(value: T): Success<T, E>;
759
+ /**
760
+ * Creates a {@link Result.Failure} instance.
761
+ */
762
+ export function error<E, T = never>(error: E): Failure<T, E>;
763
+ /**
764
+ * Wraps a synchronous operation that might throw in a {@link Result}.
765
+ */
766
+ export function wrap<V, E = Error>(callback: () => V, catcher?: (err: unknown) => E): Result<V, E>;
767
+ /**
768
+ * Converts a nullable value into a {@link Result}.
769
+ * Returns {@link Result.Failure} if the value is `null` or `undefined`.
770
+ */
771
+ export function nonNullOr<V, E>(nullable: V | null | undefined, err: E): Result<NonNullable<V>, E>;
772
+ /**
773
+ * Converts a nullable value into a {@link Result} or executes a fallback {@link Result}-returning function.
774
+ */
775
+ export function nonNullOrElse<V, W, E>(nullable: V | null | undefined, orElse: () => Result<W, E>): Result<NonNullable<V> | W, E>;
776
+ /**
777
+ * Repeatedly executes a {@link Result}-returning body while a condition is met.
778
+ */
779
+ export function repeat<V, E>(initialValue: V, condition: (value: V) => boolean, body: (value: V) => Result<V, E>): Result<V, E>;
780
+ /**
781
+ * Reduces a collection into a {@link Result} by executing a {@link Result}-returning
782
+ * reducer for each item.
783
+ */
784
+ export function reduce<T, V, E>(items: T[], reducer: (accumulator: V, item: T) => Result<V, E>, initialValue: V): Result<V, E>;
785
+ /**
786
+ * Collapses an array of {@link Result}s into a single {@link Result} containing an array of values.
787
+ * Returns the first {@link Result.Failure} encountered.
788
+ * Similar to {@link Promise.all}, but for synchronous {@link Result} collections.
789
+ */
790
+ export function all<V, E>(results: Result<V, E>[]): Result<V[], E>;
791
+ /**
792
+ * Returns the first {@link Result.Success} produced by the callback for any item
793
+ * in the collection. If no success is found, it returns the provided default error {@link Result}.
794
+ * Similar to {@link Promise.any}, but for synchronous {@link Result} collections.
795
+ */
796
+ export function any<T, V, E>(items: T[], callback: (item: T) => Result<V, E>, fallback: Result<V, E>): Result<V, E>;
797
+ /**
798
+ * Validates a subject against a type guard, producing a {@link Result}.
799
+ */
800
+ export function require<T, U extends T, V, E>(subject: T, condition: (subject: T) => subject is U, createValue: (subject: U) => V, createError: (subject: T) => E): Result<V, E>;
801
+ }
802
+
541
803
  /**
542
804
  * Rounds a value.
543
805
  * @param value - The value to round.