generaltranslation 8.0.6 → 8.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # generaltranslation
 
+## 8.1.0
+
+### Minor Changes
+
+- [#872](https://github.com/generaltranslation/gt/pull/872) [`3e8ceb4`](https://github.com/generaltranslation/gt/commit/3e8ceb4526530d38eae469b05e8bf273d5ca05ac) Thanks [@ErnestM1234](https://github.com/ErnestM1234)! - feat: formatCutoff()
+
 ## 8.0.6
 
 ### Patch Changes

package/dist/cache/IntlCache.d.ts

@@ -1,8 +1,26 @@
+import { ConstructorType, CustomIntlConstructors } from './types';
+/**
+ * Cache for Intl and custom format instances to avoid repeated instantiation
+ * Uses a two-level structure: constructor name -> cache key -> instance
+ */
 declare class IntlCache {
     private cache;
     constructor();
+    /**
+     * Generates a consistent cache key from locales and options
+     * Handles all LocalesArgument types (string, Locale, array, undefined)
+     */
     private _generateKey;
-    get<K extends keyof typeof Intl>(constructor: K, locales: string | string[], options?: {}): InstanceType<(typeof Intl)[K]>;
+    /**
+     * Gets a cached Intl instance or creates a new one if not found
+     * @param constructor The name of the Intl constructor to use
+     * @param args Constructor arguments (locales, options)
+     * @returns Cached or newly created Intl instance
+     */
+    get<K extends keyof CustomIntlConstructors>(constructor: K, ...args: ConstructorParameters<CustomIntlConstructors[K]>): InstanceType<ConstructorType<K>>;
 }
+/**
+ * Global instance of the Intl cache for use throughout the application
+ */
 export declare const intlCache: IntlCache;
 export {};

package/dist/cache/types.d.ts

@@ -0,0 +1,32 @@
+import { CutoffFormatConstructor } from '../formatting/custom-formats/CutoffFormat/CutoffFormat';
+/**
+ * Extracts only the constructor functions from the Intl namespace,
+ * filtering out static methods like getCanonicalLocales and supportedValuesOf
+ */
+type IntlConstructors = {
+    [K in keyof typeof Intl as (typeof Intl)[K] extends new (...args: any[]) => any ? K : never]: (typeof Intl)[K];
+};
+/**
+ * Extended interface that includes all native Intl constructors plus custom ones
+ */
+export interface CustomIntlConstructors extends IntlConstructors {
+    CutoffFormat: typeof CutoffFormatConstructor;
+}
+/**
+ * Helper type to represent a constructor function for a given Intl constructor key
+ */
+export type ConstructorType<K extends keyof CustomIntlConstructors> = new (...args: ConstructorParameters<CustomIntlConstructors[K]>) => InstanceType<CustomIntlConstructors[K]>;
+/**
+ * Type for the cache object structure - each constructor gets its own Record
+ * mapping cache keys to instances of that specific constructor type
+ */
+export type IntlCacheObject = {
+    [K in keyof CustomIntlConstructors]?: Record<string, InstanceType<ConstructorType<K>>>;
+};
+/**
+ * Type for the CustomIntl object that maps constructor names to constructor functions
+ */
+export type CustomIntlType = {
+    [K in keyof CustomIntlConstructors]: ConstructorType<K>;
+};
+export {};

package/dist/errors/formattingErrors.d.ts

@@ -0,0 +1 @@
+export declare const createInvalidCutoffStyleError: (style: string) => string;

package/dist/formatting/custom-formats/CutoffFormat/CutoffFormat.d.ts

@@ -0,0 +1,59 @@
+import { CutoffFormat, CutoffFormatOptions, PostpendedCutoffParts, PrependedCutoffParts, ResolvedCutoffFormatOptions } from './types';
+export declare class CutoffFormatConstructor implements CutoffFormat {
+    private locale;
+    private options;
+    private additionLength;
+    /**
+     * Constructor
+     * @param {string | string[]} locales - The locales to use for formatting.
+     * @param {CutoffFormatOptions} options - The options for formatting.
+     * @param {number} [option.maxChars] - The maximum number of characters to display.
+     * - Undefined values are treated as no cutoff.
+     * - Negative values follow .slice() behavior and terminator will be added before the value.
+     * - 0 will result in an empty string.
+     * - If cutoff results in an empty string, no terminator is added.
+     * @param {CutoffFormatStyle} [option.style='ellipsis'] - The style of the terminator.
+     * @param {string} [option.terminator] - Optional override the terminator to use.
+     * @param {string} [option.separator] - Optional override the separator to use between the terminator and the value.
+     * - If no terminator is provided, then separator is ignored.
+     *
+     * @example
+     * const format = new CutoffFormat('en', { maxChars: 5 });
+     * format.format('Hello, world!'); // 'Hello...'
+     *
+     * const format = new CutoffFormat('en', { maxChars: -3 });
+     * format.format('Hello, world!'); // '...ld!'
+     */
+    constructor(locales: Intl.LocalesArgument, options?: CutoffFormatOptions);
+    /**
+     * Format a value according to the cutoff options, returning a formatted string.
+     *
+     * @param {string} value - The string value to format with cutoff behavior.
+     * @returns {string} The formatted string with terminator applied if cutoff occurs.
+     *
+     * @example
+     * const formatter = new CutoffFormatConstructor('en', { maxChars: 8, style: 'ellipsis' });
+     * formatter.format('Hello, world!'); // Returns 'Hello, w...'
+     */
+    format(value: string): string;
+    /**
+     * Format a value to parts according to the cutoff options, returning an array of string parts.
+     * This method breaks down the formatted result into individual components for more granular control.
+     *
+     * @param {string} value - The string value to format with cutoff behavior.
+     * @returns {PrependedCutoffParts | PostpendedCutoffParts} An array of string parts representing the formatted result.
+     *   - For positive maxChars: [cutoffValue, separator?, terminator?]
+     *   - For negative maxChars: [terminator?, separator?, cutoffValue]
+     *   - For no cutoff: [originalValue]
+     *
+     * @example
+     * const formatter = new CutoffFormatConstructor('en', { maxChars: 5, style: 'ellipsis' });
+     * formatter.formatToParts('Hello, world!'); // Returns ['Hello', '...']
+     */
+    formatToParts(value: string): PrependedCutoffParts | PostpendedCutoffParts;
+    /**
+     * Get the resolved options
+     * @returns {ResolvedCutoffFormatOptions} The resolved options.
+     */
+    resolvedOptions(): ResolvedCutoffFormatOptions;
+}

package/dist/formatting/custom-formats/CutoffFormat/constants.d.ts

@@ -0,0 +1,4 @@
+import { CutoffFormatStyle, ResolvedTerminatorOptions } from './types';
+export declare const DEFAULT_CUTOFF_FORMAT_STYLE: CutoffFormatStyle;
+export declare const DEFAULT_TERMINATOR_KEY = "DEFAULT_TERMINATOR_KEY";
+export declare const TERMINATOR_MAP: Record<CutoffFormatStyle, Record<string | typeof DEFAULT_TERMINATOR_KEY, ResolvedTerminatorOptions>>;

package/dist/formatting/custom-formats/CutoffFormat/types.d.ts

@@ -0,0 +1,48 @@
+/** Type of terminator */
+export type CutoffFormatStyle = 'none' | 'ellipsis';
+/** Terminator options */
+export interface TerminatorOptions {
+    /** The terminator to use */
+    terminator?: string;
+    /** An optional separator between the terminator and the value */
+    separator?: string;
+}
+/** Input formatting options (for constructor) */
+export interface CutoffFormatOptions extends TerminatorOptions {
+    /** Cutoff length */
+    maxChars?: number;
+    /** Type of terminator */
+    style?: CutoffFormatStyle;
+}
+/** Resolved terminator options */
+export interface ResolvedTerminatorOptions extends TerminatorOptions {
+    terminator: string | undefined;
+    separator: string | undefined;
+}
+/** Resolved options (after constructor) */
+export interface ResolvedCutoffFormatOptions extends CutoffFormatOptions, ResolvedTerminatorOptions {
+    maxChars: number | undefined;
+    style: CutoffFormatStyle | undefined;
+    terminator: string | undefined;
+    separator: string | undefined;
+}
+/** Prepended cutoff list */
+export type PrependedCutoffParts = [string] | [ResolvedTerminatorOptions['terminator'], string] | [
+    ResolvedTerminatorOptions['terminator'],
+    ResolvedTerminatorOptions['separator'],
+    string
+];
+/** Postpended cutoff list */
+export type PostpendedCutoffParts = [string] | [string, ResolvedTerminatorOptions['terminator']] | [
+    string,
+    ResolvedTerminatorOptions['separator'],
+    ResolvedTerminatorOptions['terminator']
+];
+/**
+ * Cutoff Class interface
+ */
+export interface CutoffFormat {
+    format: (value: string) => string;
+    resolvedOptions: () => ResolvedCutoffFormatOptions;
+    formatToParts: (value: string) => PrependedCutoffParts | PostpendedCutoffParts;
+}