@zelgadis87/utils-core 4.0.0

package/src/time/types.ts

@@ -0,0 +1,56 @@
+import { TDigit, TDigit1_9, TNumber0_1000, TParseableInt } from "../types";
+
+export type TOneDigit = `${TDigit}`;
+export type TTwoDigits = `${TDigit}${TDigit}`;
+export type TThreeDigits = `${TDigit}${TDigit}${TDigit}`;
+export type TFourDigits = `${TDigit}${TDigit}${TDigit}${TDigit}`;
+
+export type TUpToTwoDigits = TOneDigit | `${TDigit1_9}${TDigit}`;
+export type TUpToThreeDigits = TUpToTwoDigits | `${TDigit1_9}${TDigit}${TDigit}`;
+export type TUpToFourDigits = TUpToThreeDigits | `${TDigit1_9}${TDigit}${TDigit}${TDigit}`;
+
+export type TTwoDigitsMonth = TTwoDigits & TParseableInt<`0${TDigit1_9}` | '10' | '11' | '12'>;
+export type TTwoDigitsDate = TTwoDigits & TParseableInt<`0${TDigit1_9}` | `1${TDigit}` | `2${TDigit}` | '30' | '31'>;
+export type TTwoDigitsHour = TTwoDigits & TParseableInt<`0${TDigit1_9}` | `1${TDigit}` | '20' | '21' | '22' | '23' | '24'>;
+export type TTwoDigitsMinute = TTwoDigits & TParseableInt<`0${TDigit1_9}` | `1${TDigit}` | `2${TDigit}` | `3${TDigit}` | `4${TDigit}` | `5${TDigit}`>;
+export type TTwoDigitsSecond = TTwoDigits & TParseableInt<`0${TDigit1_9}` | `1${TDigit}` | `2${TDigit}` | `3${TDigit}` | `4${TDigit}` | `5${TDigit}`>;
+export type TThreeDigitsMillisecond = TThreeDigits;
+export type TFourDigitsYear = TFourDigits;
+export type TFourDigitsMillisecond = `${'+' | '-'}${TThreeDigits}`;
+
+export type TMonth = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+
+export type TDayOfMonth = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+	| 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19
+	| 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29
+	| 30 | 31;
+
+export type TWeekNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+	| 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19
+	| 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29
+	| 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39
+	| 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49
+	| 50 | 51 | 52 | 53;
+
+export type TDayOfWeek = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export type THourOfDay = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+| 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19
+| 20 | 21 | 22 | 23;
+export type TMinuteOfHour = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+	| 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19
+	| 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29
+	| 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39
+	| 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49
+	| 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59;
+export type TSecondOfMinute = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+	| 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19
+	| 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29
+	| 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39
+	| 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49
+	| 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59;
+export type TMillisecondOfSecond = TNumber0_1000;
+
+// Need to use strings here, as digit types are too complex to represent.
+export type TIso8601DateString = `${string}-${string}-${string}T${string}:${string}:${string}.${string}${string}`;
+export type TIso8601DateUtcString = `${string}-${string}-${string}T${string}:${string}:${string}.${string}Z`;
+

package/src/types/arrays.ts

@@ -0,0 +1,89 @@
+import { TComparisonFunction } from "../sorting/index.js";
+import { TBiPredicate } from "./functions.js";
+import { TMaybe } from "./nulls.js";
+
+export type TReadableArray<T> = Array<T> | ReadonlyArray<T>;
+export type TArrayable<T> = T | T[];
+export type TEmptyArray = [];
+
+export function ensureArray<const T>( t: T | Array<T> ): Array<T> {
+	return t instanceof Array ? t : [ t ];
+}
+export function ensureReadableArray<const T>( t: T | Array<T> | ReadonlyArray<T> ): TReadableArray<T> {
+	return t instanceof Array ? t : [ t ];
+}
+
+export function isArray<const T>( t: unknown ): t is Array<T> {
+	return t instanceof Array;
+}
+
+/**
+ * Generate a new copy of an array with:
+ * - the first instance of an item matching the predicate being replaced with the given argument
+ * - the given argument added as last item of the array if the predicate did not produce a match
+ * @param arr - the original array of items
+ * @param item - the item to insert or update
+ * @param predicate - a function that returns true iff an item is equal to the given argument
+ * @returns a new copy of the array with the item updated or added in last place
+ */
+export function upsert<T>( arr: ReadonlyArray<T>, item: T, isEqual: TBiPredicate<T> ): Array<T> {
+	const index = arr.findIndex( a => isEqual( a, item ) );
+	if ( index === -1 ) {
+		return [ ...arr, item ];
+	} else {
+		return [
+			...arr.slice( 0, index ),
+			item,
+			...arr.slice( index + 1 )
+		];
+	}
+}
+
+export function range( start: number, end: number ): Array<number> {
+	if ( end < start ) throw new Error();
+	let length = ( end - start ) + 1;
+	return new Array( length ).fill( 1 ).map( ( _, i ) => start + i );
+}
+
+export function fill<T>( length: number, value: T ): Array<T> {
+	return new Array<T>( length ).fill( value );
+}
+
+export function extendArray<T extends Record<string | number | symbol, unknown>, X extends Record<string | number | symbol, unknown>>( arr: TReadableArray<T>, props: X ): Array<( T & X )> {
+	return arr.map( ( t: T ) => ( {
+		...t,
+		...props
+	} ) );
+}
+
+export function extendArrayWith<T extends Record<string | number | symbol, unknown>, X extends Record<string | number | symbol, unknown>>( arr: TReadableArray<T>, propsFn: ( t: T ) => X ): Array<( T & X )> {
+	return arr.map( ( t: T ) => ( {
+		...t,
+		...propsFn( t )
+	} ) );
+}
+
+export function reverse<T>( arr: TReadableArray<T> ): Array<T> {
+	return [ ...arr ].reverse();
+}
+
+export function head<T>( arr: TReadableArray<T>, defaultValue: TMaybe<T> = null ): TMaybe<T> {
+	return ( arr.length ? arr[ 0 ] : defaultValue );
+}
+
+export function last<T>( arr: TReadableArray<T>, defaultValue: TMaybe<T> = null ): TMaybe<T> {
+	return head( reverse( arr ), defaultValue );
+}
+
+export function sortedArray<T>( arr: Array<T>, sortFn?: TComparisonFunction<T> | undefined ): Array<T>;
+export function sortedArray<T>( arr: ReadonlyArray<T>, sortFn?: TComparisonFunction<T> | undefined ): ReadonlyArray<T>;
+export function sortedArray<T>( arr: TReadableArray<T>, sortFn?: TComparisonFunction<T> | undefined ) {
+	return [ ...arr ].sort( sortFn );
+}
+
+/**
+ * Custom implementation of includes which allows checking for arbitrary items inside the array.
+ */
+export function includes<T>( arr: TReadableArray<T>, item: unknown, fromIndex?: number ) {
+	return arr.includes( item as any, fromIndex );
+}

package/src/types/booleans.ts

@@ -0,0 +1,8 @@
+
+export function isTrue( x: unknown ): x is true {
+	return x === true;
+}
+
+export function isFalse( x: unknown ): x is false {
+	return x === false;
+}

package/src/types/functions.ts

@@ -0,0 +1,27 @@
+
+export type TFunction<A, R> = ( a: A ) => R;
+export type TVoidFunction = TFunction<void, void>
+export type TProducer<R> = TFunction<void, R>;
+export type TConsumer<T> = TFunction<T, void>;
+export type TPredicate<T> = TFunction<T, boolean>;
+export type TIdentityFunction<T> = TFunction<T, T>;
+
+export type TBiFunction<A, B, R> = ( a: A, b: B ) => R;
+export type TBiConsumer<A, B> = TBiFunction<A, B, void>
+export type TBiPredicate<T> = TBiFunction<T, T, boolean>;
+
+export type TAsyncFunction<A, R> = TFunction<A, Promise<R>>;
+export type TAsyncVoidFunction = TAsyncFunction<void, void>
+export type TAsyncProducer<R> = TAsyncFunction<void, R>;
+export type TAsyncConsumer<T> = TAsyncFunction<T, void>;
+export type TAsyncPredicate<T> = TAsyncFunction<T, boolean>;
+export type TAsyncBiFunction<A, B, R> = TBiFunction<A, B, Promise<R>>;
+export type TAsyncBiConsumer<A, B> = TAsyncBiFunction<A, B, void>;
+export type TAsyncBiPredicate<T> = TAsyncBiFunction<T, T, boolean>;
+
+export type TAnyFunction<R> = ( ...args: unknown[] ) => R;
+export type TAsyncAnyFunction<R> = ( ...args: unknown[] ) => Promise<R>;
+
+export function isFunction( t: unknown ): t is Function { // eslint-disable-line @typescript-eslint/no-unsafe-function-type
+	return typeof t === 'function';
+}

package/src/types/index.ts

@@ -0,0 +1,18 @@
+
+// Semantic only
+
+export type TTimeoutHandle = ReturnType<typeof setTimeout>;
+export type TIntervalHandle = ReturnType<typeof setInterval>;
+
+export type TPrimitive = string | number | boolean | null;
+
+export * from './arrays';
+export * from './booleans.ts';
+export * from './functions';
+export * from './json';
+export * from './nulls';
+export * from './numbers';
+export * from './promises';
+export * from './records';
+export * from './strings';
+

package/src/types/json.ts

@@ -0,0 +1,5 @@
+
+export type TJsonPrimitive = string | number | boolean | null | undefined;
+export type TJsonArray = Array<TJsonSerializable> | ReadonlyArray<TJsonSerializable>;
+export type TJsonObject = { [ key: string ]: TJsonSerializable }
+export type TJsonSerializable = TJsonPrimitive | TJsonArray | TJsonObject;

package/src/types/nulls.ts

@@ -0,0 +1,33 @@
+import { TConsumer, TFunction } from "./functions.js";
+
+export type TMaybe<T> = T | null;
+
+export function ensureDefined<T>( v: T, name = 'value' ): T {
+	if ( isDefined( v ) )
+		return v;
+	throw new Error( 'Expected ' + name + ' to be defined, got: ' + v );
+}
+
+export function isDefined<T>( x: T | null | undefined ): x is T {
+	return x !== null && x !== undefined;
+}
+
+export function isNullOrUndefined( x: unknown ): x is null | undefined {
+	return x === null || x === undefined;
+}
+
+export function ifDefined<R>( source: TMaybe<R>, callback: TConsumer<R> ): void {
+	if ( isDefined( source ) )
+		callback( source );
+}
+
+export function mapDefined<R, S>( source: TMaybe<R>, mapper: TFunction<R, S> ): TMaybe<S> {
+	if ( isDefined( source ) )
+		return mapper( source );
+	return null;
+}
+
+export function ifNullOrUndefined( source: TMaybe<unknown>, callback: TConsumer<void> ): void {
+	if ( isNullOrUndefined( source ) )
+		callback();
+}

package/src/types/numbers.ts

@@ -0,0 +1,80 @@
+import { TFunction } from "./functions.js";
+
+
+export type TNumericString = `${number}`;
+export type TNumericFloatingPointString = `${number}.${number}`;
+export type TPositiveNumber = number; // Only used for semantics. Cannot do better typechecking at the moment.
+export type TNegativeNumber = number; // Only used for semantics. Cannot do better typechecking at the moment.
+
+export type TZero = 0;
+export type TDigit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+export type TDigit1_9 = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+export type TNumber0_100 = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100;
+export type TNumber0_1000 = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 |
+	100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 |
+	200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 |
+	300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 | 349 | 350 | 351 | 352 | 353 | 354 | 355 | 356 | 357 | 358 | 359 | 360 | 361 | 362 | 363 | 364 | 365 | 366 | 367 | 368 | 369 | 370 | 371 | 372 | 373 | 374 | 375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 | 389 | 390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | 398 | 399 |
+	400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 419 | 420 | 421 | 422 | 423 | 424 | 425 | 426 | 427 | 428 | 429 | 430 | 431 | 432 | 433 | 434 | 435 | 436 | 437 | 438 | 439 | 440 | 441 | 442 | 443 | 444 | 445 | 446 | 447 | 448 | 449 | 450 | 451 | 452 | 453 | 454 | 455 | 456 | 457 | 458 | 459 | 460 | 461 | 462 | 463 | 464 | 465 | 466 | 467 | 468 | 469 | 470 | 471 | 472 | 473 | 474 | 475 | 476 | 477 | 478 | 479 | 480 | 481 | 482 | 483 | 484 | 485 | 486 | 487 | 488 | 489 | 490 | 491 | 492 | 493 | 494 | 495 | 496 | 497 | 498 | 499 |
+	500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 509 | 510 | 511 | 512 | 513 | 514 | 515 | 516 | 517 | 518 | 519 | 520 | 521 | 522 | 523 | 524 | 525 | 526 | 527 | 528 | 529 | 530 | 531 | 532 | 533 | 534 | 535 | 536 | 537 | 538 | 539 | 540 | 541 | 542 | 543 | 544 | 545 | 546 | 547 | 548 | 549 | 550 | 551 | 552 | 553 | 554 | 555 | 556 | 557 | 558 | 559 | 560 | 561 | 562 | 563 | 564 | 565 | 566 | 567 | 568 | 569 | 570 | 571 | 572 | 573 | 574 | 575 | 576 | 577 | 578 | 579 | 580 | 581 | 582 | 583 | 584 | 585 | 586 | 587 | 588 | 589 | 590 | 591 | 592 | 593 | 594 | 595 | 596 | 597 | 598 | 599 |
+	600 | 601 | 602 | 603 | 604 | 605 | 606 | 607 | 608 | 609 | 610 | 611 | 612 | 613 | 614 | 615 | 616 | 617 | 618 | 619 | 620 | 621 | 622 | 623 | 624 | 625 | 626 | 627 | 628 | 629 | 630 | 631 | 632 | 633 | 634 | 635 | 636 | 637 | 638 | 639 | 640 | 641 | 642 | 643 | 644 | 645 | 646 | 647 | 648 | 649 | 650 | 651 | 652 | 653 | 654 | 655 | 656 | 657 | 658 | 659 | 660 | 661 | 662 | 663 | 664 | 665 | 666 | 667 | 668 | 669 | 670 | 671 | 672 | 673 | 674 | 675 | 676 | 677 | 678 | 679 | 680 | 681 | 682 | 683 | 684 | 685 | 686 | 687 | 688 | 689 | 690 | 691 | 692 | 693 | 694 | 695 | 696 | 697 | 698 | 699 |
+	700 | 701 | 702 | 703 | 704 | 705 | 706 | 707 | 708 | 709 | 710 | 711 | 712 | 713 | 714 | 715 | 716 | 717 | 718 | 719 | 720 | 721 | 722 | 723 | 724 | 725 | 726 | 727 | 728 | 729 | 730 | 731 | 732 | 733 | 734 | 735 | 736 | 737 | 738 | 739 | 740 | 741 | 742 | 743 | 744 | 745 | 746 | 747 | 748 | 749 | 750 | 751 | 752 | 753 | 754 | 755 | 756 | 757 | 758 | 759 | 760 | 761 | 762 | 763 | 764 | 765 | 766 | 767 | 768 | 769 | 770 | 771 | 772 | 773 | 774 | 775 | 776 | 777 | 778 | 779 | 780 | 781 | 782 | 783 | 784 | 785 | 786 | 787 | 788 | 789 | 790 | 791 | 792 | 793 | 794 | 795 | 796 | 797 | 798 | 799 |
+	800 | 801 | 802 | 803 | 804 | 805 | 806 | 807 | 808 | 809 | 810 | 811 | 812 | 813 | 814 | 815 | 816 | 817 | 818 | 819 | 820 | 821 | 822 | 823 | 824 | 825 | 826 | 827 | 828 | 829 | 830 | 831 | 832 | 833 | 834 | 835 | 836 | 837 | 838 | 839 | 840 | 841 | 842 | 843 | 844 | 845 | 846 | 847 | 848 | 849 | 850 | 851 | 852 | 853 | 854 | 855 | 856 | 857 | 858 | 859 | 860 | 861 | 862 | 863 | 864 | 865 | 866 | 867 | 868 | 869 | 870 | 871 | 872 | 873 | 874 | 875 | 876 | 877 | 878 | 879 | 880 | 881 | 882 | 883 | 884 | 885 | 886 | 887 | 888 | 889 | 890 | 891 | 892 | 893 | 894 | 895 | 896 | 897 | 898 | 899 |
+	900 | 901 | 902 | 903 | 904 | 905 | 906 | 907 | 908 | 909 | 910 | 911 | 912 | 913 | 914 | 915 | 916 | 917 | 918 | 919 | 920 | 921 | 922 | 923 | 924 | 925 | 926 | 927 | 928 | 929 | 930 | 931 | 932 | 933 | 934 | 935 | 936 | 937 | 938 | 939 | 940 | 941 | 942 | 943 | 944 | 945 | 946 | 947 | 948 | 949 | 950 | 951 | 952 | 953 | 954 | 955 | 956 | 957 | 958 | 959 | 960 | 961 | 962 | 963 | 964 | 965 | 966 | 967 | 968 | 969 | 970 | 971 | 972 | 973 | 974 | 975 | 976 | 977 | 978 | 979 | 980 | 981 | 982 | 983 | 984 | 985 | 986 | 987 | 988 | 989 | 990 | 991 | 992 | 993 | 994 | 995 | 996 | 997 | 998 | 999
+export type TNumber0_5 = 0 | 1 | 2 | 3 | 4 | 5;
+export type TNumber0_10 = TNumber0_5 | 6 | 7 | 8 | 9 | 10;
+export type TNumber0_15 = TNumber0_10 | 11 | 12 | 13 | 14 | 15;
+export type TNumber0_20 = TNumber0_15 | 16 | 17 | 18 | 19 | 20;
+export type TNumber1_10 = Exclude<TNumber0_10, 0>;
+
+export type TParseInt<T> = T extends `${infer N extends number}` ? N : never;
+export type TParseableInt<T> = T extends `${number}` ? T : never;
+
+export function ensurePositiveNumber( v: number, name = 'value' ): number {
+	if ( v !== undefined && v !== null && v > 0 )
+		return v;
+	throw new Error( `Expected ${name} to be positive, got: ${v}` );
+}
+export function ensureNonNegativeNumber( v: number, name = 'value' ): number {
+	if ( v !== undefined && v !== null && v >= 0 )
+		return v;
+	throw new Error( `Expected ${name} to be non-negative, got: ${v}` );
+}
+export function ensureNonPositiveNumber( v: number, name = 'value' ): number {
+	if ( v !== undefined && v !== null && v <= 0 )
+		return v;
+	throw new Error( `Expected ${name} to be non-positive, got: ${v}` );
+}
+export function ensureNegativeNumber( v: number, name = 'value' ): number {
+	if ( v !== undefined && v !== null && v < 0 )
+		return v;
+	throw new Error( `Expected ${name} to be negative, got: ${v}` );
+}
+
+export function incrementBy( n: number ): TFunction<number, number> {
+	return ( v ) => v + n;
+}
+export function multiplyBy( n: number ): TFunction<number, number> {
+	return ( v ) => v * n;
+}
+export function divideBy( n: number ): TFunction<number, number> {
+	return ( v ) => v / n;
+}
+export const increment = incrementBy( 1 );
+export const decrement = incrementBy( -1 );
+export const decrementBy = ( n: number ) => incrementBy( -n );
+
+export function isNumber( v: unknown ): v is number {
+	return typeof v === "number";
+}
+
+export function isPositiveNumber( v: number ): v is TPositiveNumber {
+	return v > 0;
+}
+
+export function isNegativeNumber( v: number ): v is TNegativeNumber {
+	return v < 0;
+}
+
+export function isZero( v: number ): v is TZero {
+	return v === 0;
+}

package/src/types/promises.ts

@@ -0,0 +1,23 @@
+import TimeDuration from "../time/TimeDuration.js";
+import { TAsyncFunction, TFunction } from "./functions.js";
+
+export type TPromisable<T> = T | Promise<T>;
+
+export function asPromise<T>( promisable: TPromisable<T> ): Promise<T> {
+	return Promise.resolve( promisable );
+}
+
+export function promiseSequence<R>( ...fns: TFunction<void, Promise<R>>[] ): TFunction<void, Promise<R[]>> {
+	const fn = async function (): Promise<R[]> {
+		const results: R[] = [];
+		for ( let i = 0; i < fns.length; i++ ) {
+			results[ i ] = await fns[ i ]();
+		}
+		return results;
+	};
+	return fn;
+}
+
+export function delayPromise<T>( duration: TimeDuration ): TAsyncFunction<T, T> {
+	return ( result: T ) => duration.promise().then( () => result );
+}

package/src/types/records.ts

@@ -0,0 +1,21 @@
+
+export type TEmpty = Record<string, never>;
+export type TKeysOfType<T, V> = { [ K in keyof T ]-?: T[ K ] extends V ? K : never }[ keyof T ];
+
+export function dictToList<T>( obj: Record<string | number, T> ): T[] {
+	return Object.keys( obj ).map( key => obj[ key ] );
+}
+
+export function pick<T extends object, K extends keyof T>( o: T, keys: K[] ): Pick<T, K> {
+	return keys.reduce( ( obj, key ) => {
+		obj[ key ] = o[ key ];
+		return obj;
+	}, {} as Pick<T, K> );
+}
+
+export type TOptionsWithoutDefaults<T, R> = Partial<T> & Required<Omit<T, keyof R>>;
+export type TOptionalKeysForType<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? K : never }[keyof T];
+export type TRequiredKeysForType<T> = Exclude<keyof T, TOptionalKeysForType<T>>;
+export type TAllKeysOptional<T> = TRequiredKeysForType<T> extends never ? true : false;
+export type TConditionalParameter<T> = TAllKeysOptional<T> extends true ? T | undefined : T;
+export type TConditionalParameterOptions<T, R> = TConditionalParameter<TOptionsWithoutDefaults<T, R>>;

package/src/types/strings.ts

@@ -0,0 +1,143 @@
+import { range, TReadableArray } from "./arrays.js";
+import { isNullOrUndefined, TMaybe } from "./nulls.js";
+
+// Semantic-only
+export type THtmlString = string;
+export type TUrl = string;
+export type TRelativeUrl = string;
+
+export function hashCode( str: string ): number {
+	let hash = 0
+	for ( let i = 0; i < str.length; ++i )
+		hash = Math.imul( 31, hash ) + str.charCodeAt( i )
+	return hash | 0
+}
+
+export function repeat( char: string, times: number ): string {
+	return times > 0 ? range( 0, times - 1 ).map( _ => char ).join( '' ) : '';
+}
+
+export function capitalizeWord( word: string ): string {
+	return word[ 0 ].toUpperCase() + word.substring( 1 ).toLowerCase();
+}
+
+export function splitWords( text: string, regEx: RegExp = /\s+/ ): string[] {
+	return text.split( regEx ).filter( t => t.length > 0 );
+}
+
+export function stringToNumber( s: string | null | undefined ): number | null {
+	if ( isNullOrUndefined( s ) )
+		return null;
+	return Number( s );
+}
+
+export class StringParts {
+
+	private readonly _parts: string[]
+
+	private constructor( ...parts: string[] ) {
+		this._parts = parts;
+	}
+
+	public toUpperCase() {
+		return new StringParts( ...this.parts.map( part => part.toUpperCase() ) );
+	}
+
+	public toLowerCase() {
+		return new StringParts( ...this.parts.map( part => part.toLowerCase() ) );
+	}
+
+	public capitalizeFirst() {
+		if ( !this.length ) return this;
+		return new StringParts( capitalizeWord( this.first! ), ...this.tail.map( part => part.toLowerCase() ) );
+	}
+
+	public capitalizeEach() {
+		return new StringParts( ...this.parts.map( part => capitalizeWord( part ) ) );
+	}
+
+	public get parts() {
+		return this._parts;
+	}
+
+	public get tail() {
+		const [ _first, ...tail ] = this.parts;
+		return tail;
+	}
+
+	public get first(): TMaybe<string> {
+		return this._parts[ 0 ] ?? null;
+	}
+
+	public get last(): TMaybe<string> {
+		return this._parts[ this.length - 1 ] ?? null;
+	}
+
+	public get length() {
+		return this._parts.length;
+	}
+
+	public trim() {
+		return new StringParts( ...this.parts.map( part => part.trim() ) )
+	}
+
+	public toSnakeCase() {
+		return this.toLowerCase().join( '_' );
+	}
+
+	public toCamelCase() {
+		if ( !this.length ) return '';
+		return [ this.first!.toLowerCase(), ...this.tail.map( capitalizeWord ) ].join( '' );
+	}
+
+	public toKebabCase() {
+		return this.toLowerCase().join( '-' );
+	}
+
+	public toPascalCase() {
+		return this.capitalizeEach().join( '' );
+	}
+
+	public toHumanCase() {
+		return this.capitalizeFirst().join( ' ' );
+	}
+
+	public join( separator: string ) {
+		return this.parts.join( separator );
+	}
+
+	public mergeWith( { parts: otherParts }: { parts: TReadableArray<string> } ) {
+		return new StringParts( ...this.parts, ...otherParts )
+	}
+
+	public slice( start: number, end?: number ) {
+		return new StringParts( ...this.parts.slice( start, end ) )
+	}
+
+	public splice( start: number, deleteCount: number, ...items: string[] ) {
+		return new StringParts( ...this.parts.splice( start, deleteCount, ...items ) )
+	}
+
+	public push( part: string ) {
+		return new StringParts( ...this.parts, part )
+	}
+
+	public shift( part: string ) {
+		return new StringParts( part, ...this.parts )
+	}
+
+	public reverse() {
+		return new StringParts( ...this.parts.reverse() )
+	}
+
+	public static fromString = ( s: string, separator: string | RegExp = /\s+/g ) => {
+		if ( s === null || separator === null )
+			throw new Error( 'Invalid arguments' );
+		return new StringParts( ...s.split( separator ) );
+	}
+
+	public static fromParts = ( ...parts: string[] ) => {
+		return new StringParts( ...parts );
+	}
+
+}

package/src/upgrade/DataUpgrader.ts

@@ -0,0 +1,100 @@
+
+import { isDefined, isNumber, isPositiveNumber, TJsonSerializable } from "../types/index.ts";
+import { jsonCloneDeep } from "../utils";
+import { EmptyUpgradeError, UnavailableUpgradeError } from "./errors";
+import getTransitionsPath from "./getTransitionsPath";
+import { TPossibleFromVersion, TPossibleVersion, TTransitionMatrix, TUpgradable, TUpgradeFunction, TVersionMap } from "./types";
+
+const VERSION_FIELD = "$version";
+
+export interface IDataUpgrader<XStar extends TUpgradable, XLatest extends XStar> {
+	upgrade( data: XStar ): Promise<XLatest>;
+}
+
+export class DataUpgrader<X extends TUpgradable, XLatest extends X> implements IDataUpgrader<X, XLatest> {
+
+	private transitions: TTransitionMatrix<X> = {};
+
+	private constructor(
+		private latestVersion: XLatest[ typeof VERSION_FIELD ]
+	) { }
+
+	public addTransition<
+		XFrom extends TVersionMap<X>[ XFromNumber ],
+		XTo extends TVersionMap<X>[ XToNumber ],
+		XFromNumber extends TPossibleFromVersion<X, XLatest>,
+		XToNumber extends Exclude<TPossibleVersion<X>, XFromNumber>,
+	>(
+		from: XFromNumber,
+		to: XToNumber,
+		apply: TUpgradeFunction<X, XFrom, XTo>
+	): this {
+		if ( from === undefined || from < 0 )
+			throw new Error( `Invalid argument from, non-negative number expected, got: ${from}` );
+		if ( to === undefined || to <= 0 )
+			throw new Error( `Invalid argument to, positive number expected, got: ${to}` );
+		if ( to <= from )
+			throw new Error( `Invalid argument to, expected number greater than ${from}, got: ${to}` );
+		if ( to > this.latestVersion )
+			throw new Error( `Invalid argument to, expected number lower than ${this.latestVersion}, got: ${to}` );
+		if ( this.transitions[ to ]?.[ from ] )
+			throw new Error( `Invalid transition arguments, duplicated transition found from ${from} to ${to}` );
+		const toMatrix: TTransitionMatrix<X>[ XTo[ typeof VERSION_FIELD ] ] = this.transitions[ to ] ?? {};
+		toMatrix[ from ] = { from, to, apply };
+		this.transitions[ to ] = toMatrix;
+
+		return this;
+	}
+
+	public async upgrade( data: X ): Promise<XLatest> {
+		if ( !data || typeof data !== "object" )
+			throw new Error( `Invalid argument data, object expected, got: ${typeof data}.` );
+		if ( data.$version === null || data.$version === undefined || typeof data.$version !== "number" )
+			throw new Error( `Invalid argument data, version metadata required, got: ${data.$version as unknown as string}` );
+		if ( data.$version > this.latestVersion )
+			throw new Error( `Invalid argument data, version metadata is in the future: ${data.$version}, current: ${this.latestVersion}` );
+		if ( this.isLatestVersion( data ) )
+			return data;
+
+		const from = data.$version;
+		const to = this.latestVersion;
+		const path = getTransitionsPath<X, typeof from, XLatest[ typeof VERSION_FIELD ]>( this.transitions, from, to );
+		if ( path === null )
+			throw new UnavailableUpgradeError( data, from, to );
+
+		let current: X = jsonCloneDeep( data );
+		for ( const transition of path ) {
+			const next = await transition.apply( current as any );
+			if ( next === null || next === undefined )
+				throw new EmptyUpgradeError( current, from, to );
+			current = next;
+		}
+
+		return current as XLatest;
+	}
+
+	public isLatestVersion( data: X ): data is XLatest {
+		return data.$version === this.latestVersion;
+	}
+
+	public static create<
+		X extends TUpgradable,
+		XLatestVersion extends X,
+	>(
+		latest: XLatestVersion[ typeof VERSION_FIELD ]
+	) {
+		return new DataUpgrader<X, XLatestVersion>( latest );
+	}
+
+	public static Errors = {
+		EmptyUpgrade: EmptyUpgradeError,
+		UnavailableUpgrade: UnavailableUpgradeError
+	} as const;
+
+}
+
+export function isUpgradable( obj: TJsonSerializable ): obj is TUpgradable {
+	return isDefined( obj ) && typeof obj === "object" && VERSION_FIELD in obj && isNumber( obj.$version ) && isPositiveNumber( obj.$version );
+}
+
+export default DataUpgrader;

package/src/upgrade/errors.ts

@@ -0,0 +1,25 @@
+
+
+export class UnavailableUpgradeError<T> extends Error {
+
+	constructor(
+		public readonly data: T,
+		public readonly from: number,
+		public readonly to: number
+	) {
+		super( `No transition found to upgrade data from version ${from} to version ${to}.` );
+	}
+
+}
+
+export class EmptyUpgradeError<T> extends Error {
+
+	constructor(
+		public readonly data: T,
+		public readonly from: number,
+		public readonly to: number,
+	) {
+		super( `Transition from version ${ from } to version ${ to } resulted in empty data` );
+	}
+
+}