@dereekb/util 13.15.0 → 13.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.15.0",
+  "version": "13.17.0",
   "sideEffects": false,
   "exports": {
     "./test": {

package/src/lib/hash.d.ts

@@ -58,3 +58,25 @@ export declare function makeHashDecodeMap(decodeValues: string[], hashFn: (value
  * @returns Plaintext recovered via `decodeMap`, dropping any hash missing from it.
  */
 export declare function decodeHashedValuesWithDecodeMap(hashedValues: string[], decodeMap: HashDecodeMap): string[];
+/**
+ * Computes a stable, non-negative 32-bit integer hash for the input string using the FNV-1a algorithm.
+ *
+ * Deterministic and dependency-free (no `Math.random`): the same input always yields the same value,
+ * making it suitable for deterministically mapping a string onto a fixed-size set (e.g. picking a
+ * curated color for a name via `hashStringToNumber(value) % colors.length`).
+ *
+ * @param value - String to hash.
+ * @returns A non-negative integer in the range `[0, 2^32)`.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory hash
+ * @dbxUtilTags hash, string, number, deterministic, fnv, bucket, index
+ * @dbxUtilRelated decode-hashed-values
+ *
+ * @example
+ * ```ts
+ * hashStringToNumber('Michelle B'); // stable integer, same every call
+ * hashStringToNumber('Michelle B') % 12; // deterministic bucket index 0-11
+ * ```
+ */
+export declare function hashStringToNumber(value: string): number;

package/src/lib/string/string.d.ts

@@ -247,6 +247,91 @@ export type FirstNameLastNameTuple = [string, Maybe<string>];
  * @dbxUtilRelated split-join-remainder
  */
 export declare function splitJoinNameString(input: string): FirstNameLastNameTuple;
+/**
+ * Default maximum number of initials produced by a {@link NameToInitialsFunction}.
+ */
+export declare const DEFAULT_NAME_TO_INITIALS_MAX_INITIALS = 2;
+/**
+ * Default minimum number of initials produced by a {@link NameToInitialsFunction}.
+ */
+export declare const DEFAULT_NAME_TO_INITIALS_MIN_INITIALS = 1;
+/**
+ * Configuration for creating a {@link NameToInitialsFunction}.
+ */
+export interface NameToInitialsConfig {
+    /**
+     * Maximum number of initials to produce.
+     *
+     * Caps the number of leading words used for multi-word inputs and the number of leading characters used for single-word inputs. Defaults to {@link DEFAULT_NAME_TO_INITIALS_MAX_INITIALS}.
+     */
+    readonly maxInitials?: Maybe<number>;
+    /**
+     * Minimum number of initials to produce.
+     *
+     * For a single-word input this many leading characters are taken (capped by `maxInitials` and the word's length). Defaults to {@link DEFAULT_NAME_TO_INITIALS_MIN_INITIALS}.
+     */
+    readonly minInitials?: Maybe<number>;
+}
+/**
+ * Derives display initials from a name or short character string.
+ *
+ * Multi-word inputs use the first character of each of the first `maxInitials` words; single-word
+ * inputs use the first `minInitials` characters verbatim. The result is always uppercased.
+ */
+export type NameToInitialsFunction = (name: string) => string;
+/**
+ * Creates a {@link NameToInitialsFunction} that derives display initials from a name or short character string.
+ *
+ * Useful for avatar fallbacks where a name (e.g. `'Michelle B'`) or a literal token (e.g. `'BB'`)
+ * should collapse to a compact label. By default a single-word input yields a single initial; raise
+ * `minInitials` to pull more leading characters from a lone word.
+ *
+ * @param config - Configuration controlling the minimum and maximum number of initials.
+ * @returns A reusable function that derives initials from input names.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, name, initials, avatar, abbreviate, person, factory
+ * @dbxUtilRelated split-join-name-string, capitalize-first-letter
+ *
+ * @example
+ * ```ts
+ * const toInitials = nameToInitialsFactory();
+ * toInitials('Michelle B'); // 'MB'
+ * toInitials('Michelle'); // 'M'
+ *
+ * const toPaddedInitials = nameToInitialsFactory({ minInitials: 2 });
+ * toPaddedInitials('Michelle'); // 'MI'
+ * toPaddedInitials('BB'); // 'BB'
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function nameToInitialsFactory(config?: Maybe<NameToInitialsConfig>): NameToInitialsFunction;
+/**
+ * Derives display initials from a name or short character string using the default configuration.
+ *
+ * Multi-word inputs use the first character of each of the first two words; single-word inputs use
+ * the first character verbatim. The result is always uppercased.
+ *
+ * @param name - Name or character string to derive initials from.
+ * @returns Uppercased initials, or an empty string when the input is blank.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, name, initials, avatar, abbreviate, person
+ * @dbxUtilRelated name-to-initials-factory, split-join-name-string, capitalize-first-letter
+ *
+ * @example
+ * ```ts
+ * nameToInitials('Michelle B'); // 'MB'
+ * nameToInitials('A'); // 'A'
+ * nameToInitials('BB'); // 'B'
+ * nameToInitials('Michelle'); // 'M'
+ * ```
+ */
+export declare const nameToInitials: NameToInitialsFunction;
 /**
  * Creates a string that repeats the given string a specified number of times.
  *

package/src/lib/type.d.ts

@@ -4,6 +4,51 @@ import { type Maybe } from './value/maybe.type';
  * Boolean, string or number value.
  */
 export type PrimativeValue = boolean | string | number;
+/**
+ * Phantom key used to nominally brand a primitive type.
+ *
+ * Declared (never defined) so it exists only in the type system and carries no
+ * runtime cost. Two `Brand<number, A>` / `Brand<number, B>` types are distinct
+ * whenever `A !== B`, which is what gives branded ids/keys their nominal identity
+ * despite sharing the same underlying primitive at runtime.
+ */
+export declare const BRAND: unique symbol;
+/**
+ * Nominally brands a primitive `TValue` with the compile-time-only tag `TBrand`.
+ *
+ * The brand is a zero-cost nominal type: the `[BRAND]` phantom key is erased at
+ * runtime, so a `Brand<number, 'UserId'>` is just a `number` once compiled, but
+ * the compiler refuses to mix it with a `Brand<number, 'PostId'>` or with a bare
+ * `number`. Use it to stop two structurally identical primitives (two id spaces,
+ * a raw count vs. a currency amount, ciphertext vs. plaintext, ...) from being
+ * accidentally interchanged.
+ *
+ * Branded values are minted at a trusted edge — a parser, a decoder, or an `as`
+ * assertion inside a constructor function — and then flow through the rest of the
+ * code as the branded type, so the "is this the right kind of value?" check is
+ * paid once rather than at every call site.
+ *
+ * @typeParam TValue - The underlying runtime representation (e.g. `number`, `string`).
+ * @typeParam TBrand - A unique string tag distinguishing this brand from others.
+ *
+ * @example
+ * ```ts
+ * type UserId = Brand<number, 'UserId'>;
+ * type PostId = Brand<number, 'PostId'>;
+ *
+ * function loadUser(id: UserId): User { ... }
+ *
+ * const userId = 10 as UserId;
+ * const postId = 10 as PostId;
+ *
+ * loadUser(userId); // ok
+ * loadUser(postId); // compile error: PostId is not assignable to UserId
+ * loadUser(10); // compile error: number is not assignable to UserId
+ * ```
+ */
+export type Brand<TValue, TBrand extends string> = TValue & {
+    readonly [BRAND]: TBrand;
+};
 /**
  * Open-ended union of known string literals `T` plus an arbitrary string fallback.
  *

package/test/index.cjs.js

@@ -223,10 +223,10 @@ function _ts_generator$2(thisArg, body) {
  * @param e - The error to pass to the callback; defaults to a generic error.
  */ function failWithTestDoneCallback(done) {
     var e = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : new Error('failed test');
-    if (done.fail != null) {
-        done.fail(e);
-    } else {
+    if (done.fail == null) {
         done(e);
+    } else {
+        done.fail(e);
     }
 }
 /**
@@ -1314,10 +1314,10 @@ function expectSuccessfulFail(errorFn) {
         return _async_to_generator(function() {
             var _testDoneCallbackRef, done, _promise, result;
             function handleError(e) {
-                if (!_instanceof(e, ExpectedFailError)) {
-                    failWithTestDoneCallback(done, e);
-                } else {
+                if (_instanceof(e, ExpectedFailError)) {
                     done();
+                } else {
+                    failWithTestDoneCallback(done, e);
                 }
             }
             return _ts_generator(this, function(_state) {

package/test/index.esm.js

@@ -221,10 +221,10 @@ function _ts_generator$2(thisArg, body) {
  * @param e - The error to pass to the callback; defaults to a generic error.
  */ function failWithTestDoneCallback(done) {
     var e = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : new Error('failed test');
-    if (done.fail != null) {
-        done.fail(e);
-    } else {
+    if (done.fail == null) {
         done(e);
+    } else {
+        done.fail(e);
     }
 }
 /**
@@ -1312,10 +1312,10 @@ function expectSuccessfulFail(errorFn) {
         return _async_to_generator(function() {
             var _testDoneCallbackRef, done, _promise, result;
             function handleError(e) {
-                if (!_instanceof(e, ExpectedFailError)) {
-                    failWithTestDoneCallback(done, e);
-                } else {
+                if (_instanceof(e, ExpectedFailError)) {
                     done();
+                } else {
+                    failWithTestDoneCallback(done, e);
                 }
             }
             return _ts_generator(this, function(_state) {

package/test/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/test",
-  "version": "13.15.0",
+  "version": "13.17.0",
   "peerDependencies": {
-    "@dereekb/util": "13.15.0",
+    "@dereekb/util": "13.17.0",
     "make-error": "^1.3.6"
   },
   "exports": {