@stevenkellner/team-conduct-api 1.0.35 → 2.0.1

package/src/types/Localization.ts

@@ -1,26 +1,100 @@
-import { keys, mapRecord, values } from '@stevenkellner/typescript-common-functionality';
+import { mapRecord } from '@stevenkellner/typescript-common-functionality';
 import { localizationEN } from '../locales/en';
 import { localizationDE } from '../locales/de';
 import { Pluralization } from './Pluralization';
+import { Locale } from './Locale';
 
-export const localizations = {
+/**
+ * Type representing the structure of a localization dictionary.
+ * Derived from the English localization as the base template.
+ */
+export type LocalizationDict = typeof localizationEN;
+
+/**
+ * Helper function to ensure a record satisfies the localization structure
+ * while preserving its concrete type.
+ */
+const satisfiesLocalizationRecord = <T extends Record<string, LocalizationDict>>(value: T): T => value;
+
+/**
+ * Record of all available localizations keyed by locale.
+ * Each localization must match the structure of LocalizationDict.
+ */
+export const localizations = satisfiesLocalizationRecord({
     en: localizationEN,
     de: localizationDE
-};
+});
 
+/**
+ * Recursive type definition for localization values.
+ * Can be nested objects, strings with template variables, or Pluralization instances.
+ */
 export type SubLocalizationType = { [Key in string]: SubLocalizationType } | string | Pluralization;
 
+/**
+ * Mapped type that transforms SubLocalizationType into corresponding localization classes.
+ * - Objects become nested SubLocalization structures
+ * - Strings become ValueLocalization instances
+ * - Pluralization instances become PluralLocalization instances
+ */
 export type SubLocalization<T extends SubLocalizationType> =
     T extends { [Key in string]: SubLocalizationType } ? { [Key in keyof T]: SubLocalization<T[Key]> } :
         T extends string ? ValueLocalization :
         T extends Pluralization ? PluralLocalization : never;
 
+/**
+ * Main localization class that provides access to localized strings.
+ * Transforms raw localization data into type-safe localization objects.
+ */
+export class Localization {
+
+    /**
+     * Returns the localization structure for the specified locale.
+     * Transforms the raw localization data into ValueLocalization and PluralLocalization instances.
+     * @param locale - The locale to retrieve localizations for
+     * @returns The complete localization structure with type-safe access
+     */
+    public static shared(locale: Locale): SubLocalization<LocalizationDict> {
+        return Localization.mapSubLocalization(localizations[locale]);
+    }
+
+    /**
+     * Recursively maps raw localization data to localization class instances.
+     * @param localization - The raw localization value to transform
+     * @returns The transformed localization with proper class instances
+     */
+    private static mapSubLocalization<T extends SubLocalizationType>(localization: T): SubLocalization<T> {
+        if (typeof localization === 'object' && ! (localization instanceof Pluralization))
+            return mapRecord(localization as Record<string, SubLocalizationType>, subLocalization => Localization.mapSubLocalization(subLocalization)) as SubLocalization<T>;
+        if (typeof localization === 'string')
+            return new ValueLocalization(localization) as SubLocalization<T>;
+        if (localization instanceof Pluralization)
+            return new PluralLocalization(localization) as SubLocalization<T>;
+        throw new Error('Invalid localization structure');
+    }
+}
+
+/**
+ * Handles localization strings with template variable substitution.
+ * Supports {{variableName}} syntax for runtime value replacement.
+ */
 export class ValueLocalization {
 
-    constructor(private readonly rawValues: Record<keyof typeof localizations, string>) {}
+    /**
+     * Creates a new ValueLocalization instance.
+     * @param rawValue - The template string with {{variable}} placeholders
+     */
+    constructor(private readonly rawValue: string) {}
 
+    /**
+     * Returns the localized string with variables substituted.
+     * Template variables in the format {{key}} are replaced with provided argument values.
+     * @param args - Record of variable names to their replacement values
+     * @returns The localized string with all variables replaced
+     * @throws Error if a required template variable is not provided in args
+     */
     public value(args: Record<string, string> = {}): string {
-        let rawValue = this.rawValues[Localization.locale];
+        let rawValue = this.rawValue;
         const regex = /\{\{(?<key>.*?)\}\}/;
         while (true) {
             const match = regex.exec(rawValue);
@@ -35,49 +109,30 @@ export class ValueLocalization {
     }
 }
 
+/**
+ * Handles pluralized localization strings that vary based on count.
+ * Combines Pluralization logic with template variable substitution.
+ */
 export class PluralLocalization {
 
-    constructor(private readonly pluralizations: Record<keyof typeof localizations, Pluralization>) {}
+    /**
+     * Creates a new PluralLocalization instance.
+     * @param pluralization - The Pluralization instance containing plural forms
+     */
+    constructor(private readonly pluralization: Pluralization) {}
 
+    /**
+     * Returns the appropriate pluralized string for the given count with variables substituted.
+     * Automatically includes 'count' in the template variables.
+     * @param count - The count to determine which plural form to use
+     * @param args - Additional template variables to substitute (count is added automatically)
+     * @returns The localized plural string with all variables replaced
+     */
     public value(count: number, args: Record<string, string> = {}): string {
-        const valueLocalization = new ValueLocalization(mapRecord(this.pluralizations, pluralization => pluralization.get(count)));
+        const valueLocalization = new ValueLocalization(this.pluralization.get(count));
         return valueLocalization.value({
             count: `${count}`,
             ...args
         });
     }
 }
-
-function swap1stAnd2ndLevel<Level1Key extends string, Level2Key extends string, T>(record: Record<Level1Key, Record<Level2Key, T>>): Record<Level2Key, Record<Level1Key, T>> {
-    const swapped = {} as Record<Level2Key, Record<Level1Key, T>>;
-    for (const key1 of keys(record)) {
-        for (const key2 of keys(record[key1]) as Level2Key[]) {
-            if (!(key2 in swapped))
-                swapped[key2] = {} as Record<Level1Key, T>;
-            swapped[key2][key1] = record[key1][key2];
-        }
-    }
-    return swapped;
-}
-
-export class Localization {
-
-    public static locale: keyof typeof localizations = 'en';
-
-    public static readonly shared = Localization.getSubLocalization(localizations);
-
-    private static getSubLocalization<T extends SubLocalizationType>(_localizations: Record<keyof typeof localizations, T>): SubLocalization<T> {
-        const _localizationValue = values(_localizations);
-        if (_localizationValue.length === 0)
-            return {} as SubLocalization<T>;
-        if (typeof _localizationValue[0] === 'object' && !(_localizationValue[0] instanceof Pluralization)) {
-            const swapped = swap1stAnd2ndLevel(_localizations as Record<string, Record<string, SubLocalizationType>>);
-            return mapRecord(swapped, subLocalization => Localization.getSubLocalization(subLocalization)) as SubLocalization<T>;
-        }
-        if (typeof _localizationValue[0] === 'string')
-            return new ValueLocalization(_localizations as Record<keyof typeof localizations, string>) as SubLocalization<T>;
-        if (_localizationValue[0] instanceof Pluralization)
-            return new PluralLocalization(_localizations as Record<keyof typeof localizations, Pluralization>) as SubLocalization<T>;
-        throw new Error('Invalid localization structure');
-    }
-}

package/src/types/MoneyAmount.ts

@@ -1,30 +1,71 @@
 import { Flattable, ITypeBuilder } from '@stevenkellner/typescript-common-functionality';
 import { Configuration } from './Configuration';
+import { Currency } from './Currency';
 
+/**
+ * Represents a monetary amount with integer value and subunit components.
+ *
+ * Stores money as two parts: main value (e.g., dollars) and subunit value (e.g., cents).
+ * This prevents floating-point precision issues in financial calculations.
+ */
 export class MoneyAmount implements Flattable<MoneyAmount.Flatten> {
 
+    /**
+     * Creates a new MoneyAmount instance.
+     *
+     * @param value - The main value (e.g., dollars, euros)
+     * @param subunitValue - The subunit value (e.g., cents), should be 0-99
+     */
     public constructor(
         public value: number,
         public subunitValue: number
     ) {}
 
+    /**
+     * Returns a MoneyAmount representing zero.
+     */
     public static get zero(): MoneyAmount {
         return new MoneyAmount(0, 0);
     }
 
+    /**
+     * Adds another MoneyAmount to this one and returns the result.
+     *
+     * Properly handles subunit overflow (e.g., 50 cents + 60 cents = 1 dollar 10 cents).
+     *
+     * @param amount - The MoneyAmount to add
+     * @returns A new MoneyAmount representing the sum
+     */
     public added(amount: MoneyAmount): MoneyAmount {
         const subunitValue = this.subunitValue + amount.subunitValue;
         const value = this.value + amount.value + Math.floor(subunitValue / 100);
         return new MoneyAmount(value, subunitValue % 100);
     }
 
+    /**
+     * Multiplies this MoneyAmount by a factor and returns the result.
+     *
+     * Properly handles subunit calculations and overflow.
+     *
+     * @param factor - The multiplication factor
+     * @returns A new MoneyAmount representing the product
+     */
     public multiplied(factor: number): MoneyAmount {
         const subunitValue = this.subunitValue * factor;
         const value = this.value * factor + Math.floor(subunitValue / 100);
         return new MoneyAmount(value, subunitValue % 100);
     }
 
-    public formatted(currency: Configuration.Currency, configuration: Configuration): string {
+    /**
+     * Returns a localized formatted string representation of the amount.
+     *
+     * Uses Intl.NumberFormat for proper currency formatting based on locale.
+     *
+     * @param currency - The currency code (e.g., 'USD', 'EUR')
+     * @param configuration - Configuration containing locale information
+     * @returns Formatted currency string (e.g., "$12.50", "12,50 €")
+     */
+    public formatted(currency: Currency, configuration: Configuration): string {
         const numberFormat = Intl.NumberFormat(configuration.locale, {
             style: 'currency',
             currency: currency
@@ -32,10 +73,18 @@ export class MoneyAmount implements Flattable<MoneyAmount.Flatten> {
         return numberFormat.format(this.value + this.subunitValue / 100);
     }
 
+    /**
+     * Returns the complete monetary value as a decimal number.
+     *
+     * @returns The total value (e.g., 12.50 for 12 dollars and 50 cents)
+     */
     public get completeValue(): number {
         return this.value + this.subunitValue / 100;
     }
 
+    /**
+     * Returns the flattened representation as a decimal number.
+     */
     public get flatten(): MoneyAmount.Flatten {
         return this.value + this.subunitValue / 100;
     }
@@ -43,14 +92,31 @@ export class MoneyAmount implements Flattable<MoneyAmount.Flatten> {
 
 export namespace MoneyAmount {
 
+    /**
+     * Flattened representation of MoneyAmount as a decimal number.
+     */
     export type Flatten = number;
 
+    /**
+     * Type builder for MoneyAmount serialization/deserialization.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, MoneyAmount> {
 
+        /**
+         * Builds a MoneyAmount instance from a flattened decimal value.
+         *
+         * Separates the decimal into integer and subunit parts.
+         *
+         * @param value - Decimal value (e.g., 12.50)
+         * @returns MoneyAmount instance
+         */
         public build(value: Flatten): MoneyAmount {
             return new MoneyAmount(Math.floor(value), Math.round((value - Math.floor(value)) * 100));
         }
     }
 
+    /**
+     * Singleton instance of TypeBuilder for MoneyAmount.
+     */
     export const builder = new MoneyAmount.TypeBuilder();
 }

package/src/types/NotificationProperties.ts

@@ -1,12 +1,26 @@
 import { BytesCoder, Dictionary, Flattable, ITypeBuilder, Sha512, Tagged, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
 
+/**
+ * Represents notification properties for a user including device tokens and subscription preferences.
+ *
+ * Manages push notification device tokens (identified by hashed token IDs for security)
+ * and user preferences for which types of notifications they want to receive.
+ */
 export class NotificationProperties implements Flattable<NotificationProperties.Flatten> {
 
+    /**
+     * Creates new notification properties.
+     * @param tokens - Dictionary mapping token IDs to device tokens for push notifications (defaults to empty)
+     * @param subscriptions - Array of notification types the user is subscribed to (defaults to empty)
+     */
     public constructor(
         public tokens: Dictionary<NotificationProperties.TokenId, string> = new Dictionary(NotificationProperties.TokenId.builder),
         public subscriptions: NotificationProperties.Subscription[] = []
     ) {}
 
+    /**
+     * Gets the flattened representation of these notification properties for serialization.
+     */
     public get flatten(): NotificationProperties.Flatten {
         return {
             tokens: this.tokens.flatten,
@@ -17,10 +31,20 @@ export class NotificationProperties implements Flattable<NotificationProperties.
 
 export namespace NotificationProperties {
 
+    /**
+     * Tagged type for notification token identifiers.
+     * Token IDs are derived from hashing the actual device tokens for security.
+     */
     export type TokenId = Tagged<string, 'notificationToken'>;
 
     export namespace TokenId {
 
+        /**
+         * Creates a token ID from a device token by hashing it with SHA-512.
+         * Only the first 16 characters of the hash are used as the identifier.
+         * @param token - The device push notification token
+         * @returns A hashed token ID for secure storage and lookup
+         */
         export function create(token: string): TokenId {
             const hasher = new Sha512();
             const tokenBytes = BytesCoder.fromUtf8(token);
@@ -30,38 +54,72 @@ export namespace NotificationProperties {
             return new Tagged(rawId, 'notificationToken');
         }
 
+        /**
+         * Flattened representation of a token ID (plain string).
+         */
         export type Flatten = string;
 
+        /**
+         * Builder for constructing TokenId instances from strings.
+         */
         export const builder = Tagged.builder('notificationToken' as const, new ValueTypeBuilder<string>());
     }
 
-    export type Subscription =
-        | 'new-fine'
-        | 'fine-reminder'
-        | 'fine-state-change';
+    /**
+     * Available notification subscription types.
+     */
+    const subscriptions = [
+        'new-fine',
+        'fine-reminder',
+        'fine-state-change'
+    ] as const;
+
+    /**
+     * Type representing the available notification subscription options.
+     * - new-fine: Notifications when a new fine is created
+     * - fine-reminder: Reminder notifications for unpaid fines
+     * - fine-state-change: Notifications when a fine's status changes
+     */
+    export type Subscription = typeof subscriptions[number];
 
     export namespace Subscription {
 
-        export const all: Subscription[] = [
-            'new-fine',
-            'fine-reminder',
-            'fine-state-change'
-        ]
+        /**
+         * Readonly array of all available subscription types.
+         */
+        export const all: readonly Subscription[] = subscriptions
 
+        /**
+         * Builder for constructing Subscription values from strings.
+         */
         export const builder = new ValueTypeBuilder<Subscription>();
     }
 
+    /**
+     * Flattened representation of notification properties for serialization.
+     */
     export type Flatten = {
         tokens: Dictionary.Flatten<string>,
         subscriptions: Subscription[]
     };
 
+    /**
+     * Builder for constructing NotificationProperties from flattened data.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, NotificationProperties> {
 
+        /**
+         * Builds a NotificationProperties instance from flattened data.
+         * @param value - The flattened notification properties data
+         * @returns A new NotificationProperties instance
+         */
         public build(value: Flatten): NotificationProperties {
             return new NotificationProperties(Dictionary.builder(TokenId.builder, new ValueTypeBuilder<string>()).build(value.tokens), value.subscriptions);
         }
     }
 
+    /**
+     * Singleton builder instance for NotificationProperties.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/PayedState.ts

@@ -1,41 +1,36 @@
 import { ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
 import { Localization } from './Localization';
+import { Locale } from './Locale';
 
-export type PayedState =
-    | 'payed'
-    | 'notPayed';
+const payedStates = ['payed', 'notPayed'] as const;
 
-export namespace PayedState {
-
-    export const all: PayedState[] = ['payed', 'notPayed'];
+/**
+ * Represents the payment status of a fine.
+ *
+ * Can be either 'payed' (fine has been paid) or 'notPayed' (fine is unpaid).
+ */
+export type PayedState = typeof payedStates[number];
 
-    export function formatted(state: PayedState): string {
-        return Localization.shared.payedState[state].value();
-    }
+export namespace PayedState {
 
-    export function toggled(state: PayedState): PayedState {
-        switch (state) {
-        case 'payed':
-            return 'notPayed';
-        case 'notPayed':
-            return 'payed';
-        }
-    }
+    /**
+     * Array containing all possible payment states.
+     */
+    export const all: readonly PayedState[] = payedStates;
 
-    export function payedTag(state: PayedState): { value: string; severity: 'secondary' | 'danger' } {
-        switch (state) {
-        case 'payed':
-            return {
-                value: formatted(state),
-                severity: 'secondary'
-            };
-        case 'notPayed':
-            return {
-                value: formatted(state),
-                severity: 'danger'
-            };
-        }
+    /**
+     * Returns the localized display string for a payment state.
+     *
+     * @param state - The payment state to format
+     * @param locale - The locale to use for formatting
+     * @returns Localized string representation of the payment state
+     */
+    export function formatted(state: PayedState, locale: Locale): string {
+        return Localization.shared(locale).payedState[state].value();
     }
 
+    /**
+     * Type builder for PayedState serialization/deserialization.
+     */
     export const builder = new ValueTypeBuilder<PayedState>();
 }

package/src/types/Person.ts

@@ -3,8 +3,21 @@ import { PersonSignInProperties } from './PersonSignInProperties';
 import { Fine } from './Fine';
 import { Flattable, Guid, ITypeBuilder, Tagged } from '@stevenkellner/typescript-common-functionality';
 
+/**
+ * Represents a person within a team, including their personal details, assigned fines, and optional sign-in properties.
+ *
+ * A person can have multiple fines assigned to them and may or may not be signed in (have sign-in properties).
+ */
 export class Person implements Flattable<Person.Flatten> {
 
+    /**
+     * Creates a new Person instance.
+     *
+     * @param id - Unique identifier for the person (GUID)
+     * @param properties - Private properties including first name and optional last name
+     * @param fineIds - Array of fine IDs assigned to this person (defaults to empty array)
+     * @param signInProperties - Optional sign-in properties if the person has signed in (defaults to null)
+     */
     public constructor(
         public id: Person.Id,
         public properties: PersonPrivateProperties,
@@ -12,6 +25,9 @@ export class Person implements Flattable<Person.Flatten> {
         public signInProperties: PersonSignInProperties | null = null
     ) {}
 
+    /**
+     * Returns the flattened representation of the person for serialization.
+     */
     public get flatten(): Person.Flatten {
         return {
             id: this.id.flatten,
@@ -21,6 +37,11 @@ export class Person implements Flattable<Person.Flatten> {
         };
     }
 
+    /**
+     * Returns the person's full name.
+     *
+     * If lastName is null, returns only firstName. Otherwise returns "firstName lastName".
+     */
     public get name(): string {
         if (this.properties.lastName === null)
             return this.properties.firstName;
@@ -30,15 +51,27 @@ export class Person implements Flattable<Person.Flatten> {
 
 export namespace Person {
 
+    /**
+     * Tagged GUID type for person identifiers.
+     */
     export type Id = Tagged<Guid, 'person'>;
 
     export namespace Id {
 
+        /**
+         * Flattened representation of a person ID (GUID string).
+         */
         export type Flatten = string;
 
+        /**
+         * Type builder for Person.Id serialization/deserialization.
+         */
         export const builder = Tagged.builder('person' as const, Guid.builder);
     }
 
+    /**
+     * Flattened representation of a Person for serialization.
+     */
     export type Flatten = {
         id: Id.Flatten,
         properties: PersonPrivateProperties.Flatten,
@@ -46,8 +79,17 @@ export namespace Person {
         signInProperties: PersonSignInProperties.Flatten | null,
     }
 
+    /**
+     * Type builder for Person serialization/deserialization.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, Person> {
 
+        /**
+         * Builds a Person instance from flattened data.
+         *
+         * @param value - Flattened person data
+         * @returns Person instance
+         */
         public build(value: Flatten): Person {
             return new Person(
                 Id.builder.build(value.id),
@@ -58,5 +100,8 @@ export namespace Person {
         }
     }
 
+    /**
+     * Singleton instance of TypeBuilder for Person.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/PersonPrivateProperties.ts

@@ -1,12 +1,26 @@
 import { Flattable, ITypeBuilder } from '@stevenkellner/typescript-common-functionality';
 
+/**
+ * Represents the private properties of a person.
+ *
+ * Contains personal information that is private to the person,
+ * such as their name. The last name is optional.
+ */
 export class PersonPrivateProperties implements Flattable<PersonPrivateProperties.Flatten> {
 
+    /**
+     * Creates new person private properties.
+     * @param firstName - The first name of the person
+     * @param lastName - The last name of the person (null if not provided)
+     */
     constructor(
         public firstName: string,
         public lastName: string | null
     ) {}
 
+    /**
+     * Gets the flattened representation of these properties for serialization.
+     */
     public get flatten(): PersonPrivateProperties.Flatten {
         return {
             firstName: this.firstName,
@@ -17,13 +31,24 @@ export class PersonPrivateProperties implements Flattable<PersonPrivatePropertie
 
 export namespace PersonPrivateProperties {
 
+    /**
+     * Flattened representation of person private properties for serialization.
+     */
     export type Flatten = {
         firstName: string;
         lastName: string | null;
     }
 
+    /**
+     * Builder for constructing PersonPrivateProperties from flattened data.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, PersonPrivateProperties> {
 
+        /**
+         * Builds a PersonPrivateProperties instance from flattened data.
+         * @param value - The flattened person private properties data
+         * @returns A new PersonPrivateProperties instance
+         */
         public build(value: Flatten): PersonPrivateProperties {
             return new PersonPrivateProperties(
                 value.firstName,
@@ -32,6 +57,8 @@ export namespace PersonPrivateProperties {
         }
     }
 
+    /**
+     * Singleton builder instance for PersonPrivateProperties.
+     */
     export const builder = new TypeBuilder();
 }
-