@prozilla-os/shared 1.4.0 → 1.5.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.
@@ -0,0 +1,17 @@
1
+ import { a, L as t, b as n, i as c, c as i, d as p, e as r, f as o, g, h as l, j as L, k as b, l as f } from "./chunks/index-PU_xBoDn.js";
2
+ export {
3
+ a as Ansi,
4
+ t as LogLevel,
5
+ n as Logger,
6
+ c as inspect,
7
+ i as inspectArray,
8
+ p as inspectError,
9
+ r as inspectFunction,
10
+ o as inspectFunctionCall,
11
+ g as inspectMap,
12
+ l as inspectObject,
13
+ L as inspectReactElement,
14
+ b as inspectSet,
15
+ f as inspectString
16
+ };
17
+ //# sourceMappingURL=logging.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logging.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}
package/dist/main.d.ts CHANGED
@@ -122,7 +122,6 @@ export declare const ANSI: {
122
122
  * @hideconstructor
123
123
  */
124
124
  export declare class Ansi {
125
- #private;
126
125
  /**
127
126
  * Makes text black using {@link ANSI.fg.black}.
128
127
  */
@@ -211,6 +210,7 @@ export declare class Ansi {
211
210
  * Makes text strike through using {@link ANSI.decoration.strike}.
212
211
  */
213
212
  static strike(text: string): string;
213
+ static apply(text: string, code: string): string;
214
214
  /**
215
215
  * Removes all ANSI escape sequences.
216
216
  */
@@ -221,6 +221,8 @@ export declare class Ansi {
221
221
  static stripColors(text: string): string;
222
222
  }
223
223
 
224
+ export declare const BASE_URL = "https://os.prozilla.dev/";
225
+
224
226
  export declare abstract class BaseResult<V, E> {
225
227
  /**
226
228
  * Returns `true` if this result is a {@link Result.Success}.
@@ -278,6 +280,13 @@ export declare abstract class BaseResult<V, E> {
278
280
 
279
281
  declare function bold(text: string): string;
280
282
 
283
+ /**
284
+ * Transforms the first character of a string to uppercase.
285
+ * @param string - The string to capitalize.
286
+ * @returns The string with the first character transformed to uppercase.
287
+ */
288
+ export declare function capitalize<S extends string = string>(string: S): Capitalize<S>;
289
+
281
290
  /**
282
291
  * Clamps a value between an upper and lower bound.
283
292
  * @param value - The value to clamp.
@@ -331,6 +340,14 @@ export declare class EventEmitter<T extends Record<keyof T, unknown[]>> {
331
340
  emitAsync<K extends keyof T>(event: K, ...args: T[K]): Promise<void>;
332
341
  }
333
342
 
343
+ export declare function fillTemplate(template: string, properties: Record<string, string>, options: {
344
+ join: false;
345
+ }): string[];
346
+
347
+ export declare function fillTemplate(template: string, properties: Record<string, string>, options?: {
348
+ join?: true | string;
349
+ }): string;
350
+
334
351
  /**
335
352
  * Formats time relative to now.
336
353
  * @param date - The date.
@@ -371,6 +388,314 @@ declare function heading6(text: string): string;
371
388
 
372
389
  declare function horizontalRule(): string;
373
390
 
391
+ /**
392
+ * Generates a human-readable string representation of a value.
393
+ *
394
+ * This is intended for debugging purposes.
395
+ * It is an alternative to {@link https://nodejs.org/api/util.html#utilinspectobject-options util.inspect}, that supports more customization of the output.
396
+ *
397
+ * @param value - The value to inspect.
398
+ * @param options - Optional inspection options.
399
+ * @returns The resulting string.
400
+ * @example
401
+ * **Note:** The following examples omit the `options` parameter for simplicity. In reality, the return values will contain ANSI escape codes unless you explicitly set `colors` to `false`.
402
+ * ```tsx
403
+ * // Supports primitive values.
404
+ * inspect(null) === "null"
405
+ * inspect("example") === "\"example\""
406
+ *
407
+ * // Supports objects and arrays (and other containers).
408
+ * inspect({ size: 2, values: [true, false] }) === "{ size: 2, values: [true, false] }"
409
+ *
410
+ * // Even supports React nodes.
411
+ * inspect(<h1>Example</h1>) === "<h1>Example</h1>"
412
+ * ```
413
+ */
414
+ export declare function inspect(value: unknown, options?: InspectionOptions): string;
415
+
416
+ /**
417
+ * Returns a string representation of an array.
418
+ * @param array - The array to inspect.
419
+ * @param options - Optional inspection options.
420
+ * @returns The resulting string.
421
+ * @example
422
+ * **Note:** The following examples omit or shorten the `options` parameter for simplicity. In reality, the return values will contain ANSI escape codes unless you explicitly set `colors` to `false`.
423
+ * ```ts
424
+ * inspect([1, 2, 3]) === "[1, 2, 3]"
425
+ * inspect([1, 2, 3], { spaceAfterComma: false }) === "[1,2,3]"
426
+ * ```
427
+ */
428
+ export declare function inspectArray(array: unknown[], options?: InspectionOptions): string;
429
+
430
+ /**
431
+ * Returns a string representation of an error.
432
+ * @param error - The error to inspect.
433
+ * @param options - Optional inspection options.
434
+ * @returns The resulting string.
435
+ */
436
+ export declare function inspectError(error: Error, options?: InspectionOptions): string;
437
+
438
+ /**
439
+ * Returns a string representation of a function.
440
+ * @param func - The function to inspect.
441
+ * @param options - Optional inspection options.
442
+ * @returns The resulting string.
443
+ */
444
+ export declare function inspectFunction(func: Function, options?: InspectionOptions): string;
445
+
446
+ /**
447
+ * Returns a string representation of a function call, its arguments and its return value.
448
+ * @param func - The function to inspect.
449
+ * @param args - The arguments of the function call.
450
+ * @param returnValue - The return value of the function call.
451
+ * @param options - Optional inspection options.
452
+ * @returns The resulting string.
453
+ */
454
+ export declare function inspectFunctionCall<A extends unknown[] = [], R = undefined>(func: (...args: A) => R, args: A, returnValue: R, options?: InspectionOptions): string;
455
+
456
+ /**
457
+ * Configuration options for the inspection utilities.
458
+ * @see {@link inspect}
459
+ */
460
+ export declare interface InspectionOptions {
461
+ /**
462
+ * The maximum depth for representations of container values (e.g., objects, arrays).
463
+ * @default 2
464
+ */
465
+ depth?: number;
466
+ /**
467
+ * The maximum number of array elements to represent before truncating.
468
+ * @default 100
469
+ */
470
+ maxArrayLength?: number;
471
+ /**
472
+ * The maximum amount of characters of a string to represent, before replacing the remainder with an ellipsis.
473
+ * @default 80
474
+ */
475
+ maxStringLength?: number;
476
+ /**
477
+ * The maximum line length before wrapping to a new line.
478
+ *
479
+ * This option is ignored when {@link compact} is set to `true`.
480
+ * @default 60
481
+ */
482
+ breakLength?: number;
483
+ /**
484
+ * `true` keeps container values on a single line when possible.
485
+ * @default true
486
+ */
487
+ compact?: boolean;
488
+ /**
489
+ * `true` enables the sorting of keys in object representations.
490
+ * @default false
491
+ */
492
+ sortKeys?: boolean;
493
+ /**
494
+ * `true` uses single quotes instead of double quotes.
495
+ * @default false
496
+ */
497
+ singleQuotes?: boolean;
498
+ /**
499
+ * `true` places a space after every comma.
500
+ * @default true
501
+ */
502
+ spaceAfterComma?: boolean;
503
+ /**
504
+ * Plugins to extend, override or configure the inspection process.
505
+ */
506
+ plugins?: InspectionPlugin[];
507
+ /**
508
+ * The {@link ANSI} color codes for different symbols.
509
+ *
510
+ * Set to `false` to disable ANSI colors.
511
+ */
512
+ colors?: false | {
513
+ /**
514
+ * The color to apply to strings.
515
+ * @default ANSI.fg.green
516
+ */
517
+ string?: string | null;
518
+ /**
519
+ * The color to apply to numbers.
520
+ * @default ANSI.fg.yellow
521
+ */
522
+ number?: string | null;
523
+ /**
524
+ * The color to apply to booleans.
525
+ * @default ANSI.fg.yellow
526
+ */
527
+ boolean?: string | null;
528
+ /**
529
+ * The color to apply to `null` keywords.
530
+ * @default ANSI.decoration.dim + ANSI.fg.yellow
531
+ */
532
+ null?: string | null;
533
+ /**
534
+ * The color to apply to `undefined` keywords.
535
+ * @default ANSI.decoration.dim + ANSI.fg.yellow
536
+ */
537
+ undefined?: string | null;
538
+ /**
539
+ * The color to apply to bigints.
540
+ * @default ANSI.fg.yellow
541
+ */
542
+ bigint?: string | null;
543
+ /**
544
+ * The color to apply to symbols.
545
+ * @default ANSI.fg.green
546
+ */
547
+ symbol?: string | null;
548
+ /**
549
+ * The color to apply to functions.
550
+ * @default ANSI.fg.blue
551
+ */
552
+ function?: string | null;
553
+ /**
554
+ * The color to apply to keys.
555
+ * @default ANSI.fg.white
556
+ */
557
+ key?: string | null;
558
+ /**
559
+ * The color to apply to dates.
560
+ * @default ANSI.fg.magenta
561
+ */
562
+ date?: string | null;
563
+ /**
564
+ * The color to apply to {@link RegExp}s.
565
+ * @default ANSI.fg.cyan
566
+ */
567
+ regExp?: string | null;
568
+ /**
569
+ * The color to apply to errors.
570
+ * @default ANSI.fg.red
571
+ */
572
+ error?: string | null;
573
+ /**
574
+ * The color to apply to HTML tags.
575
+ * @default ANSI.fg.red
576
+ */
577
+ htmlTag?: string | null;
578
+ /**
579
+ * The color to apply to React components.
580
+ * @default ANSI.fg.yellow
581
+ */
582
+ reactComponent?: string | null;
583
+ /**
584
+ * The color to apply to delimiters.
585
+ * @default ANSI.fg.cyan
586
+ */
587
+ delimiter?: string | null;
588
+ };
589
+ }
590
+
591
+ /**
592
+ * A plugin for the inspection utilities.
593
+ *
594
+ * Can be used to extend, override or configure the inspection process.
595
+ * Hook methods are called at different stages of the process and can seamlessly interact with it.
596
+ *
597
+ * This is heavily inspired by [Vite's plugin API](https://vite.dev/guide/api-plugin) and follows a similar pattern.
598
+ *
599
+ * @see {@link inspect}
600
+ */
601
+ export declare interface InspectionPlugin {
602
+ /** The name of this plugin. */
603
+ name: string;
604
+ /**
605
+ * A hook that configures the inspection options before any values are inspected.
606
+ * @param options - The current inspection options.
607
+ */
608
+ config?: (options: ResolvedInspectionOptions) => void;
609
+ /**
610
+ * A hook that is called before a value is inspected.
611
+ * @param input - The input value.
612
+ * @param context - The inspection context.
613
+ */
614
+ first?: (input: unknown, context: ResolvedInspectionOptions) => string | undefined;
615
+ /**
616
+ * A hook that is called if a value could not be inspected.
617
+ * @param input - The input value.
618
+ * @param context - The inspection context.
619
+ */
620
+ fallback?: (input: unknown, context: ResolvedInspectionOptions) => string | undefined;
621
+ }
622
+
623
+ /**
624
+ * Returns a string representation of a map.
625
+ * @param map - The map to inspect.
626
+ * @param options - Optional inspection options.
627
+ * @returns The resulting string.
628
+ */
629
+ export declare function inspectMap(map: Map<unknown, unknown>, options?: InspectionOptions): string;
630
+
631
+ /**
632
+ * Returns a string representation of an object.
633
+ * @param object - The object to inspect.
634
+ * @param options - Optional inspection options.
635
+ * @returns The resulting string.
636
+ * @example
637
+ * **Note:** The following example omits the `options` parameter for simplicity. In reality, the return values will contain ANSI escape codes unless you explicitly set `colors` to `false`.
638
+ * ```ts
639
+ * inspect({ first: true, second: false }) === "{ first: true, second: false }"
640
+ * ```
641
+ */
642
+ export declare function inspectObject(object: Record<PropertyKey, unknown>, options?: InspectionOptions): string;
643
+
644
+ /**
645
+ * Returns a string representation of a React element.
646
+ * @param element - The React element to inspect.
647
+ * @param options - Optional inspection options.
648
+ * @returns The resulting string.
649
+ * @example
650
+ * **Note:** The following example omits the `options` parameter for simplicity. In reality, the return values will contain ANSI escape codes unless you explicitly set `colors` to `false`.
651
+ * ```tsx
652
+ * inspect(<h1>Example</h1>) === "<h1>Example</h1>"
653
+ * ```
654
+ */
655
+ export declare function inspectReactElement(element: ReactElementLike, options?: InspectionOptions): string;
656
+
657
+ /**
658
+ * Returns a string representation of a set.
659
+ * @param set - The set to inspect.
660
+ * @param options - Optional inspection options.
661
+ * @returns The resulting string.
662
+ */
663
+ export declare function inspectSet(set: Set<unknown>, options?: InspectionOptions): string;
664
+
665
+ /**
666
+ * Generates a literal string representation of a string.
667
+ * @param string - The string to inspect.
668
+ * @param options - Optional inspection options.
669
+ * @returns The resulting string.
670
+ * @example
671
+ * **Note:** The following examples omit or shorten the `options` parameter for simplicity. In reality, the return values will contain ANSI escape codes unless you explicitly set `colors` to `false`.
672
+ * ```ts
673
+ * inspect("Example") === "\"Example\""
674
+ * inspect("Example", { singleQuotes: true }) === "'Example'"
675
+ * ```
676
+ */
677
+ export declare function inspectString(string: string, options?: InspectionOptions): string;
678
+
679
+ /**
680
+ * Inserts an item in between every item in an array.
681
+ * @param item - The item to insert.
682
+ * @param array - The array to insert into.
683
+ */
684
+ export declare function interleave<Type>(item: Type, array: Type[]): Type[];
685
+
686
+ /**
687
+ * Determines whether {@link arg} is an object.
688
+ */
689
+ export declare function isObject(arg: unknown): arg is Record<PropertyKey, unknown>;
690
+
691
+ /**
692
+ * Splits a string into an array of substrings where all substrings matching {@link searchValue} are separate items.
693
+ * @param string - The string to split.
694
+ * @param searchValue - The value to isolate from other substrings.
695
+ * @returns An array of substrings matching {@link searchValue} and the rest of the string.
696
+ */
697
+ export declare function isolateSubstring(string: string, searchValue: string): string[];
698
+
374
699
  /**
375
700
  * Checks if `input` is a valid integer.
376
701
  */
@@ -381,6 +706,13 @@ export declare function isValidInteger(input: number | string): boolean;
381
706
  */
382
707
  export declare function isValidNumber(input: number | string): boolean;
383
708
 
709
+ /**
710
+ * Checks whether a string is a valid URL.
711
+ * @param string - The string to check.
712
+ * @returns `true` if {@link string} is a URL.
713
+ */
714
+ export declare function isValidUrl(string: string): boolean;
715
+
384
716
  declare function italic(text: string): string;
385
717
 
386
718
  /**
@@ -443,6 +775,12 @@ export declare class Logger {
443
775
  prefix: {
444
776
  [key in LogLevel | "global"]?: string;
445
777
  };
778
+ /**
779
+ * The function to use to turn values into strings.
780
+ * @see {@link createStringifier}
781
+ * @default Logger.createStringifier("pretty")
782
+ */
783
+ stringify: (value: unknown) => string;
446
784
  get errorCount(): number;
447
785
  set errorCount(value: number);
448
786
  get warningCount(): number;
@@ -643,6 +981,17 @@ export declare class Logger {
643
981
  * @param level - The log level.
644
982
  */
645
983
  applyPrefix(text: string, level?: LogLevel): string;
984
+ /**
985
+ * Creates a stringify function that uses the {@link String} constructor.
986
+ * @param type - The type of stringify function to use.
987
+ */
988
+ static createStringifier(type?: "basic"): Logger["stringify"];
989
+ /**
990
+ * Creates a stringify function that uses {@link inspect} for any non-string value.
991
+ * @param type - The type of stringify function to use.
992
+ * @param options - The options for {@link inspect}.
993
+ */
994
+ static createStringifier(type: "pretty", options?: InspectionOptions): Logger["stringify"];
646
995
  }
647
996
 
648
997
  export declare enum LogLevel {
@@ -672,6 +1021,52 @@ export declare namespace Markdown {
672
1021
  }
673
1022
  }
674
1023
 
1024
+ /**
1025
+ * Merges the type of the target with one or more types of sources.
1026
+ * @typeParam Target - The target type to merge with.
1027
+ * @typeParam Sources - The source types to merge into the target type.
1028
+ */
1029
+ export declare type Merge<Target, Sources extends unknown[]> = Sources extends [] ? Target : Sources extends [infer FirstSource, ...infer OtherSources] ? Merge<MergeValues<Target, FirstSource>, OtherSources> : Sources extends (infer Source)[] ? Target | MergeValues<Target, Source> : never;
1030
+
1031
+ /**
1032
+ * Merges the types of two arrays by concatenating them.
1033
+ */
1034
+ export declare type MergeArrays<Target extends unknown[], Source extends unknown[]> = [...Target, ...Source];
1035
+
1036
+ /**
1037
+ * Recursively merges two or more objects.
1038
+ *
1039
+ * If a property is defined in two objects and the values are both objects, they are merged recursively,
1040
+ * if they are both arrays, they are concatenated, otherwise the value of the second object overrides the value of the first.
1041
+ * @param target - The target object to merge the other objects with.
1042
+ * @param sources - The objects to merge with the target object.
1043
+ * @returns The merged object.
1044
+ */
1045
+ export declare function mergeDeep<Target extends Record<PropertyKey, unknown>, Sources extends Record<PropertyKey, unknown>[] = Target[]>(target: Target, ...sources: Sources): Merge<Target, Sources>;
1046
+
1047
+ /**
1048
+ * Merges the types of two objects recursively.
1049
+ *
1050
+ * Properties are merged using {@link MergeValues}.
1051
+ */
1052
+ export declare type MergeObjects<Target extends Record<PropertyKey, unknown>, Source extends Record<PropertyKey, unknown>> = {
1053
+ [Key in keyof Target | keyof Source]: Key extends keyof Source ? Key extends keyof Target ? MergeValues<Target[Key], Source[Key]> : Source[Key] : Target[Key & keyof Target];
1054
+ };
1055
+
1056
+ /**
1057
+ * Merges the types of two primitive values.
1058
+ */
1059
+ export declare type MergePrimitive<Target, Source> = undefined extends Source ? Exclude<Source, undefined> extends never ? Target : Exclude<Source, undefined> : Source;
1060
+
1061
+ /**
1062
+ * Merges the types of two values recursively.
1063
+ *
1064
+ * Delegates to {@link MergePrimitive}, {@link MergeObjects} or {@link MergeArrays} if the two values are primitives, objects or arrays respectively.
1065
+ */
1066
+ export declare type MergeValues<Target, Source> = Target extends Record<PropertyKey, unknown> ? Source extends Record<PropertyKey, unknown> ? [Target, Source] extends [Source, Target] ? Target : MergeObjects<Target, Source> : Source : Target extends unknown[] ? Source extends unknown[] ? MergeArrays<Target, Source> : Source : MergePrimitive<Target, Source>;
1067
+
1068
+ export declare type NestedArray<T> = Array<T | NestedArray<T>>;
1069
+
675
1070
  /**
676
1071
  * Converts a string to a boolean.
677
1072
  * @param input - The string to parse.
@@ -689,6 +1084,19 @@ declare function quote(text: string): string;
689
1084
  */
690
1085
  export declare function randomFromArray<Type>(array: Type[]): Type;
691
1086
 
1087
+ /**
1088
+ * Returns a random index within the bounds of an array.
1089
+ * @returns A random index.
1090
+ */
1091
+ export declare function randomIndex(array: unknown[]): number;
1092
+
1093
+ /**
1094
+ * Returns a random integer inside a range.
1095
+ * @param min - The lower bound (inclusive).
1096
+ * @param max - The upper bound (exclusive).
1097
+ */
1098
+ export declare function randomInt(min: number, max: number): number;
1099
+
692
1100
  /**
693
1101
  * Returns a random value inside a range.
694
1102
  * @param min - The lower bound.
@@ -696,6 +1104,21 @@ export declare function randomFromArray<Type>(array: Type[]): Type;
696
1104
  */
697
1105
  export declare function randomRange(min: number, max: number): number;
698
1106
 
1107
+ export declare interface ReactElementLike {
1108
+ type: unknown;
1109
+ props?: unknown;
1110
+ key?: string | null;
1111
+ }
1112
+
1113
+ /**
1114
+ * Removes the origin/base from a URL string.
1115
+ * @param url - The URL string.
1116
+ * @returns The URL string without its origin.
1117
+ * @example
1118
+ * removeBaseUrl("https://example.com/foo/bar") === "/foo/bar"
1119
+ */
1120
+ export declare function removeBaseUrl(url: string): string;
1121
+
699
1122
  /**
700
1123
  * Removes all duplicate items from an array.
701
1124
  */
@@ -707,6 +1130,54 @@ export declare function removeDuplicatesFromArray<Type>(array: Type[]): Type[];
707
1130
  */
708
1131
  export declare function removeFromArray<Type>(item: Type, array: Type[]): void;
709
1132
 
1133
+ /**
1134
+ * Removes the URL protocol from a URL string.
1135
+ * @param url - The URL string.
1136
+ * @returns The URL string without its protocol.
1137
+ * @example
1138
+ * removeUrlProtocol("https://example.com/foo/bar") === "example.com/foo/bar"
1139
+ */
1140
+ export declare function removeUrlProtocol(url: string): string;
1141
+
1142
+ export declare function replaceAll<Type>(array: Type[], searchItem: Type, replaceItem: Type): Type[];
1143
+
1144
+ /**
1145
+ * The resolved inspection options combined with some utility functions for generating string representations.
1146
+ *
1147
+ * Used internally by the inspection utilities and {@link InspectionPlugin}s.
1148
+ * @see {@link inspect}
1149
+ */
1150
+ export declare interface ResolvedInspectionOptions extends Required<InspectionOptions> {
1151
+ /**
1152
+ * Returns a formatted delimiter string.
1153
+ * @param delimiter - The raw delimiter.
1154
+ */
1155
+ delimiter: (delimiter: string) => string;
1156
+ /** Returns a formatted separator string. */
1157
+ separator: () => string;
1158
+ /**
1159
+ * Applies color to the given string, if {@link ResolvedInspectionOptions.colors} is `true`.
1160
+ * @param text - The raw text.
1161
+ * @param colorCode - The ANSI color code to apply.
1162
+ */
1163
+ color: (text: string, colorCode: string | undefined | null) => string;
1164
+ /**
1165
+ * Applies the appropriate formatting to the given token.
1166
+ * @param token - The raw token.
1167
+ * @param type - The type of token.
1168
+ */
1169
+ token: (token: string, type?: keyof Exclude<InspectionOptions["colors"], false | undefined>) => string;
1170
+ /** Creates a new inspection context and increments the current depth. */
1171
+ fork: () => ResolvedInspectionOptions;
1172
+ }
1173
+
1174
+ /**
1175
+ * Combines an array of URL segments into a URL string.
1176
+ * @param segments - The segments of the URL.
1177
+ * @returns The combined URL.
1178
+ */
1179
+ export declare function resolveUrl(...segments: string[]): string;
1180
+
710
1181
  /**
711
1182
  * Represents either a success or a failure.
712
1183
  *
@@ -807,11 +1278,20 @@ export declare namespace Result {
807
1278
  */
808
1279
  export declare function round(value: number, precision?: number): number;
809
1280
 
1281
+ /**
1282
+ * Splits a string into two strings at a given index.
1283
+ * @param string - The string to split.
1284
+ * @param index - The index to split at.
1285
+ * @returns The parts of the string before and after the character at the given index.
1286
+ */
1287
+ export declare function splitAt(string: string, index: number): [string, string];
1288
+
810
1289
  declare function strikethrough(text: string): string;
811
1290
 
812
1291
  export declare class Vector2 {
813
1292
  x: number;
814
1293
  y: number;
1294
+ constructor();
815
1295
  constructor(xy: number);
816
1296
  constructor(x: number, y?: number);
817
1297
  static get ZERO(): Vector2;