@dereekb/util 13.9.0 → 13.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.9.0",
+  "version": "13.10.1",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -23,13 +23,13 @@
     }
   },
   "peerDependencies": {
-    "extra-set": "^3.0.0",
+    "extra-set": "^3.2.3",
     "fast-content-type-parse": "^3.0.0",
-    "make-error": "^1.3.0",
-    "ts-essentials": "^10.0.0"
+    "make-error": "^1.3.6",
+    "ts-essentials": "^10.2.0"
   },
   "devDependencies": {
-    "date-fns": "4.0.0"
+    "date-fns": "4.1.0"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/lib/array/array.boolean.d.ts

@@ -2,6 +2,10 @@ import { type ReadModelKeyFunction } from '../model/model';
 import { type Maybe } from '../value/maybe.type';
 /**
  * A string type used as a key in boolean arrays.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
  */
 export type BooleanStringKey = string;
 /**

package/src/lib/array/array.number.d.ts

@@ -65,6 +65,9 @@ export declare function reduceNumbersFn(reduceFn: (a: number, b: number) => numb
 export declare function reduceNumbersFn<D extends number>(reduceFn: (a: number, b: number) => number, emptyArrayValue?: D): (array: number[]) => number | D;
 /**
  * Exclusive end value used by range().
+ *
+ * @semanticType
+ * @semanticTopic numeric
  */
 export type RangeInputEndValue = number;
 /**

package/src/lib/auth/auth.role.claims.d.ts

@@ -4,6 +4,11 @@ import { type SetIncludesMode } from '../set';
 import { type Maybe } from '../value/maybe.type';
 /**
  * Key in the claims.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-util:auth
  */
 export type AuthClaimKey = string;
 /**

package/src/lib/auth/auth.role.d.ts

@@ -5,6 +5,11 @@ import { type Maybe } from '../value/maybe.type';
  * Is used in the client to decide which content a user can view.
  *
  * Roles should always be lowercase.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-util:auth
  */
 export type AuthRole = string;
 /**

package/src/lib/boolean.d.ts

@@ -103,6 +103,10 @@ export declare function reduceBooleansFn(reduceFn: (a: boolean, b: boolean) => b
 export type BooleanFactory = Factory<boolean>;
 /**
  * Number from 0.0 to 100.0 used for the chance to return true.
+ *
+ * @semanticType
+ * @semanticTopic percent
+ * @semanticTopic numeric
  */
 export type BooleanTrueChance = number;
 /**

package/src/lib/contact/domain.d.ts

@@ -1,6 +1,11 @@
 import { type EmailAddress } from './email';
 /**
  * Domain name portion of an email address (e.g., "example.com").
+ *
+ * @semanticType
+ * @semanticTopic email
+ * @semanticTopic contact
+ * @semanticTopic string
  */
 export type EmailAddressDomain = string;
 /**

package/src/lib/contact/email.d.ts

@@ -1,5 +1,10 @@
 /**
  * Type representing an email address as a string.
+ *
+ * @semanticType
+ * @semanticTopic email
+ * @semanticTopic contact
+ * @semanticTopic string
  */
 export type EmailAddress = string;
 /**
@@ -16,6 +21,11 @@ export interface NameEmailPair {
 export type EmailParticipant = NameEmailPair;
 /**
  * Email participant string. Starts with the email, followed by the name if available.
+ *
+ * @semanticType
+ * @semanticTopic email
+ * @semanticTopic contact
+ * @semanticTopic string
  */
 export type EmailParticipantString = string;
 /**

package/src/lib/contact/phone.d.ts

@@ -10,10 +10,20 @@ import { type Maybe } from '../value/maybe.type';
  * - +1234567890
  * - +1-555-555-5555
  * - 2345678;ext=123
+ *
+ * @semanticType
+ * @semanticTopic phone
+ * @semanticTopic contact
+ * @semanticTopic string
  */
 export type PhoneNumber = string;
 /**
  * 1-6 digit extension number
+ *
+ * @semanticType
+ * @semanticTopic phone
+ * @semanticTopic contact
+ * @semanticTopic string
  */
 export type PhoneExtensionNumber = string;
 /**

package/src/lib/date/date.d.ts

@@ -13,12 +13,20 @@ export type DateHourMinuteOrSecond = 'hour' | 'minute' | 'second';
  * I.E. "2020-04-30 00:00:00.000Z" and "2020-04-30T00:00:00.000Z"
  *
  * The only difference between this and an ISO8601DateString is the spacing between the date and time is allowed, while in ISO8601DateString it is not.
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic string
  */
 export type RFC3339DateString = string;
 /**
  * A valid ISO8601 formatted date string.
  *
  * I.E. "2020-04-30T00:00:00.000Z"
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic string
  */
 export type ISO8601DateString = string;
 /**
@@ -38,6 +46,10 @@ export declare function isISO8601DateString(input: string): input is ISO8601Date
  * A UTC date string.
  *
  * I.E. "Sat, 03 Feb 2001 04:05:06 GMT"
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic string
  */
 export type UTCDateString = string;
 /**
@@ -59,16 +71,28 @@ export declare function isUTCDateString(input: string): boolean;
  * A full ISO8601 date string that is in UTC.
  *
  * I.E. "2020-04-30T00:00:00.000Z"
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic string
  */
 export type ISO8601DateStringUTCFull = string;
 /**
  * A valid timezone string.
  *
  * I.E. "UTC", "America/Denver", etc.
+ *
+ * @semanticType
+ * @semanticTopic timezone
+ * @semanticTopic string
  */
 export type TimezoneString = string;
 /**
  * A timezone abbreviation (UTC, EST, etc).
+ *
+ * @semanticType
+ * @semanticTopic timezone
+ * @semanticTopic string
  */
 export type TimezoneAbbreviation = string;
 /**
@@ -117,6 +141,10 @@ export type DateOrDateString = Date | ISO8601DateString;
  * I.E. 1921-06-23
  *
  * NOTE: Negative years and years with more than 4 digits are not supported/expected. Support can be added later, but will require adding a more complex regex, and improved parsing in @dereekb/date
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic string
  */
 export type ISO8601DayString = string;
 /**
@@ -172,6 +200,10 @@ export declare function isISO8601DayString(input: string): input is ISO8601DaySt
 export declare function isISO8601DayStringStart(input: string): input is ISO8601DayString;
 /**
  * Date that is represented by slashes. Is considered in the Month/Day/Year format.
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic string
  */
 export type MonthDaySlashDate = string;
 /**
@@ -198,6 +230,10 @@ export declare function monthDaySlashDateToDateString(slashDate: MonthDaySlashDa
  * Time in milliseconds since the epoch.
  *
  * Returned by Date.getTime().
+ *
+ * @semanticType
+ * @semanticTopic time
+ * @semanticTopic numeric
  */
 export type UnixDateTimeMillisecondsNumber = number;
 /**
@@ -222,6 +258,11 @@ export declare function dateFromDateOrTimeMillisecondsNumber(input: Maybe<DateOr
 export declare function unixMillisecondsNumberToDate(dateTimeNumber: Maybe<UnixDateTimeMillisecondsNumber>): Maybe<Date>;
 /**
  * Number of milliseconds.
+ *
+ * @semanticType
+ * @semanticTopic time
+ * @semanticTopic duration
+ * @semanticTopic numeric
  */
 export type Milliseconds = number;
 /**
@@ -242,18 +283,38 @@ export type DateOrMilliseconds = Date | Milliseconds;
 export declare function dateOrMillisecondsToDate(dateOrMilliseconds: DateOrMilliseconds, now?: Maybe<Date>): Date;
 /**
  * Number of seconds.
+ *
+ * @semanticType
+ * @semanticTopic time
+ * @semanticTopic duration
+ * @semanticTopic numeric
  */
 export type Seconds = number;
 /**
  * Number of minutes.
+ *
+ * @semanticType
+ * @semanticTopic time
+ * @semanticTopic duration
+ * @semanticTopic numeric
  */
 export type Minutes = number;
 /**
  * Number of hours.
+ *
+ * @semanticType
+ * @semanticTopic time
+ * @semanticTopic duration
+ * @semanticTopic numeric
  */
 export type Hours = number;
 /**
  * Number of days.
+ *
+ * @semanticType
+ * @semanticTopic time
+ * @semanticTopic duration
+ * @semanticTopic numeric
  */
 export type Days = number;
 /**
@@ -306,16 +367,28 @@ export declare const DAYS_IN_WEEK: Days;
 export declare const MS_IN_WEEK: Milliseconds;
 /**
  * Day of the month, 1-31
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic numeric
  */
 export type DayOfMonth = number;
 /**
  * Month of the year, 1-12.
  *
  * NOTE: The month from Date.getMonth() is from 0-11. Use monthOfYearFromDate() to get the MonthOfYear value.
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic numeric
  */
 export type MonthOfYear = number;
 /**
  * Javascript Date month number. 0-11.
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic numeric
  */
 export type DateMonth = number;
 /**
@@ -352,6 +425,10 @@ export declare function monthOfYearFromDateMonth(dateMonth: DateMonth): MonthOfY
 export declare function makeDateMonthForMonthOfYear(monthOfYear: MonthOfYear): DateMonth;
 /**
  * Year number. I.E. 2022
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic numeric
  */
 export type YearNumber = number;
 /**

package/src/lib/date/date.time.d.ts

@@ -8,6 +8,10 @@ import { type Maybe } from '../value/maybe.type';
  * - 1:20
  * - 120AM
  * - 120
+ *
+ * @semanticType
+ * @semanticTopic time
+ * @semanticTopic string
  */
 export type ReadableTimeString = string;
 /**

package/src/lib/date/date.unix.d.ts

@@ -3,6 +3,10 @@ import { type Maybe, type MaybeNot } from '../value/maybe.type';
  * This value is in seconds since the Epoch.
  *
  * Use UnixDateTimeMillisecondsNumber instead if you need milliseconds.
+ *
+ * @semanticType
+ * @semanticTopic time
+ * @semanticTopic numeric
  */
 export type UnixDateTimeSecondsNumber = number;
 /**

package/src/lib/date/hour.d.ts

@@ -11,6 +11,10 @@ import { type Hours, type Minutes } from './date';
  *
  * - 10 minutes: 0.16
  * - 15 minutes : 0.25
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic numeric
  */
 export type FractionalHour = number;
 /**
@@ -59,6 +63,10 @@ export declare function computeNextFractionalHour(input: FractionalHour, change:
  * The minute of the day.
  *
  * Number from 0-1439.
+ *
+ * @semanticType
+ * @semanticTopic date
+ * @semanticTopic numeric
  */
 export type MinuteOfDay = number;
 export declare const MINUTE_OF_DAY_MINIUMUM = 0;

package/src/lib/encryption/encryption.object.d.ts

@@ -3,6 +3,10 @@
  *
  * Use this type to distinguish encrypted ciphertext from plain strings at the type level.
  * The actual encryption algorithm is determined by the {@link StringEncryptionProvider}.
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-util:encryption
  */
 export type EncryptedString = string;
 /**

package/src/lib/error/error.d.ts

@@ -5,6 +5,10 @@ import { type Maybe } from '../value/maybe.type';
 export type ThrowErrorFunction<T = unknown> = (error: T) => never | void;
 /**
  * A unique identifier for a specific error.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
  */
 export type StringErrorCode = string;
 /**

package/src/lib/file/file.d.ts

@@ -1,4 +1,8 @@
 /**
  * File size in bytes.
+ *
+ * @semanticType
+ * @semanticTopic measurement
+ * @semanticTopic numeric
  */
 export type FileSize = number;

package/src/lib/file/xml.d.ts

@@ -1,4 +1,8 @@
 /**
  * String value containing an XML SVG string.
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-util:xml
  */
 export type XMLSVG = string;

package/src/lib/function/function.d.ts

@@ -3,4 +3,4 @@
  *
  * Alias of MAP_IDENTITY, so `isMapIdentityFunction()` will return true for this function.
  */
-export declare const passThrough: <T>(input: T) => T;
+export { MAP_IDENTITY as passThrough } from '../value/map';

package/src/lib/hash.d.ts

@@ -1,5 +1,9 @@
 /**
  * Represents a salt value used in hashing.
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-util:hash
  */
 export type HashSalt = string;
 /**

package/src/lib/model/model.d.ts

@@ -3,18 +3,34 @@ import { type Maybe } from '../value/maybe.type';
 import { type MapFunction } from '../value/map';
 /**
  * A string model key
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
  */
 export type ModelKey = string;
 /**
  * A string model identifier (typically the document/record ID segment, not the full path).
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
  */
 export type ModelId = string;
 /**
  * Arbitrary model type.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
  */
 export type ModelTypeString = string;
 /**
  * String model key from which the model's type can be inferred from.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
  */
 export type TypedModelKey = string;
 export declare const DEFAULT_UNKNOWN_MODEL_TYPE_STRING: ModelTypeString;
@@ -46,6 +62,10 @@ export interface ModelKeyTypePair<M extends ModelTypeString = ModelTypeString> e
 }
 /**
  * An encoded ModelKeyTypePair.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
  */
 export type ModelKeyTypePairString = string;
 export interface ModelKeyNamePair extends Pick<ModelKeyTypePair, 'key'> {

package/src/lib/number/bitwise.dencoder.d.ts

@@ -7,12 +7,20 @@ import { type MapFunction } from '../value';
 export declare const MAX_BITWISE_SET_SIZE = 32;
 /**
  * Enum or number value from 0 to 31 that denotes a specific item via index of the bit to measure.
+ *
+ * @semanticType
+ * @semanticTopic numeric
+ * @semanticTopic dereekb-util:encoding
  */
 export type BitwiseEncodedSetIndex = number;
 /**
  * Set of values that are encoded into a single number.
  *
  * The number can include up to 32 unique boolean values.
+ *
+ * @semanticType
+ * @semanticTopic numeric
+ * @semanticTopic dereekb-util:encoding
  */
 export type BitwiseEncodedSet = number;
 /**

package/src/lib/number/dollar.d.ts

@@ -1,20 +1,43 @@
 import { type Maybe } from '../value/maybe.type';
 /**
  * Whole dollar amounts, before the ','.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic numeric
  */
 export type WholeDollarAmount = number;
 /**
  * Dollar amount number.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic numeric
  */
 export type DollarAmount = number;
 /**
  * Dollars amount number per hour.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic numeric
  */
 export type DollarAmountPerHour = number;
 /**
  * Dollars amount number per day.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic numeric
  */
 export type DollarAmountPerDay = number;
+/**
+ * Amount in whole cents.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic numeric
+ */
 export type CentsAmount = number;
 export interface DollarsPair {
     dollars: WholeDollarAmount;
@@ -22,12 +45,20 @@ export interface DollarsPair {
 }
 /**
  * Unit to affix to a dollar amount string.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic string
  */
 export type DollarAmountUnit = string;
 /**
  * String representing a dollar amount.
  *
  * Is formatted as a number with two decimal places. No unit is affixed.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic string
  */
 export type DollarAmountString = string;
 /**

package/src/lib/number/encoded.d.ts

@@ -9,6 +9,10 @@
  * const encoded: Radix36EncodedNumber = 'z'; // represents 35
  * const largeEncoded: Radix36EncodedNumber = '2s'; // represents 100
  * ```
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-util:encoding
  */
 export type Radix36EncodedNumber = string;
 /**
@@ -47,6 +51,10 @@ export declare function encodeRadix36Number(number: number): Radix36EncodedNumbe
 export declare function decodeRadix36Number(encoded: Radix36EncodedNumber): number;
 /**
  * A string containing only hexadecimal characters (0-9, a-f or A-F).
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-util:encoding
  */
 export type HexString = string;
 /**

package/src/lib/number/number.d.ts

@@ -8,22 +8,37 @@ import { type Maybe } from '../value/maybe.type';
  * ```ts
  * const totalUsers: Count = 42;
  * ```
+ *
+ * @semanticType
+ * @semanticTopic numeric
  */
 export type Count = number;
 /**
  * A string represented within a number.
+ *
+ * @semanticType
+ * @semanticTopic numeric
+ * @semanticTopic string
  */
 export type NumberString = string;
 /**
  * Number that represents a percent.
  *
  *  e.g. PercentNumber of 5 = 0.05 = 5%
+ *
+ * @semanticType
+ * @semanticTopic percent
+ * @semanticTopic numeric
  */
 export type PercentNumber = number;
 /**
  * A percent decimal value.
  *
  * e.g. PercentDecimal of 0.05 = 5%
+ *
+ * @semanticType
+ * @semanticTopic percent
+ * @semanticTopic numeric
  */
 export type PercentDecimal = number;
 /**

package/src/lib/number/pay.d.ts

@@ -1,8 +1,16 @@
 /**
  * Rate per hour the worker should be paid.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic numeric
  */
 export type PayRate = number;
 /**
  * The total pay amount that should be paid.
+ *
+ * @semanticType
+ * @semanticTopic currency
+ * @semanticTopic numeric
  */
 export type PayAmount = number;

package/src/lib/number/round.d.ts

@@ -14,6 +14,10 @@ export declare function roundingFunction(type: NumberRounding): RoundingFunction
 export type RoundingInput = NumberRounding | RoundingFunction;
 /**
  * The number of decimal places ot use.
+ *
+ * @semanticType
+ * @semanticTopic numeric
+ * @semanticTopic measurement
  */
 export type NumberPrecision = number;
 /**
@@ -89,10 +93,16 @@ export declare function roundToPrecision(value: number, precision: NumberPrecisi
 export declare function cutToPrecision(value: number, precision: NumberPrecision): number;
 /**
  * Number used to increase or decrease by the "step" value. When used in rounding the steps are aligned at a StepOrigin.
+ *
+ * @semanticType
+ * @semanticTopic numeric
  */
 export type StepNumber = number;
 /**
  * Origin value for StepNumbers that is used as an offset for input. Is usually 0.
+ *
+ * @semanticType
+ * @semanticTopic numeric
  */
 export type StepOrigin = number;
 /**

package/src/lib/object/object.d.ts

@@ -11,6 +11,10 @@ export type POJOKey = PrimativeKey | symbol;
 export type JsonSerializableObject = Record<PrimativeKey, any>;
 /**
  * String key of an object.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
  */
 export type ObjectKey = string;
 /**