@plyaz/types 1.3.2 → 1.3.3

package/dist/testing/features/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './cache';
+export type * from './feature-flags';

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './common';
+export type * from './features';

package/dist/translations/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';

package/dist/translations/types.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Translation leaf type.
+ * @description This type represents the structure of a translation leaf.
+ * @example
+ * const leaf: TranslationLeaf = 'Hello';
+ */
+export type TranslationLeaf = string | TranslationResourcesNested;
+/**
+ * Translation resources nested type.
+ * @description This type represents the structure of a translation resources nested.
+ * @example
+ * const nested: TranslationResourcesNested = {
+ *   hello: 'Hello',
+ * };
+ */
+export interface TranslationResourcesNested {
+    [key: string]: TranslationLeaf;
+}
+/**
+ * Translation resources type.
+ * @description This type represents the structure of translation resources.
+ * @example
+ * const resources: TranslationResources = {
+ *   en: {
+ *     common: {
+ *       hello: 'Hello',
+ *     },
+ *   },
+ * };
+ */
+export type TranslationResources = Record<string, // language code
+Record<string, // namespace
+TranslationResourcesNested>>;
+/**
+ * All translation namespaces available in the 'en' language resources.
+ * @example 'common', 'errors', etc.
+ */
+export type Namespace<Resources extends TranslationResources> = keyof Resources['en'];
+/**
+ * Helper type to remove the first element from a tuple type.
+ * Used internally by LeafPaths to track recursion depth.
+ */
+type PrevTuple<T extends readonly unknown[]> = T extends [unknown, ...infer R] ? R : [];
+/**
+ * Recursively extracts all nested keys from an object, creating dot-notation paths.
+ * @description This utility type traverses nested objects and creates dot-separated key paths.
+ * It uses a depth counter to prevent infinite recursion (max 25 levels, which should be sufficient
+ * for most translation structures while avoiding TypeScript compiler limits).
+ * @example
+ * type Paths = LeafPaths<{ a: { b: string, c: { d: string } } }>;
+ * // Result: 'a.b' | 'a.c.d'
+ * @template T - The object type to extract paths from
+ * @template Prev - The accumulated path string (used internally)
+ * @template Depth - Tuple type used to track recursion depth and prevent infinite loops
+ */
+export type LeafPaths<T, Prev extends string = '', Depth extends readonly unknown[] = [
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1
+]> = Depth['length'] extends 0 ? never : T extends string ? Prev : T extends object ? {
+    [K in keyof T]: LeafPaths<T[K], Prev extends '' ? Extract<K, string> : `${Prev}.${Extract<K, string>}`, PrevTuple<Depth>>;
+}[keyof T] : never;
+/**
+ * Type-safe union of all translation keys in the form 'namespace.key' or 'namespace.nested.key'.
+ * @description This type generates a union of all possible translation keys by combining
+ * namespace names with their nested key paths. It ensures type safety when accessing translations.
+ * @example 'common.hello', 'common.greeting', 'common.followers.zero', etc.
+ * @example use: TranslationKeys<TranslationResources, 'en'>
+ */
+export type TranslationKeys<Resources extends TranslationResources, Lang extends keyof Resources = 'en'> = {
+    [N in keyof Resources[Lang]]: `${Extract<N, string>}.${LeafPaths<Resources[Lang][N]>}`;
+}[keyof Resources[Lang]];
+/**
+ * All supported language codes, as defined in the resources object.
+ * @example 'en', 'es', 'fr', etc.
+ */
+export type SupportedLanguage = 'en' | 'es' | 'fr' | 'it' | 'pt-PT' | 'pt-BR';
+/**
+ * Configuration options for the translation system.
+ */
+export interface TranslationConfig {
+    /**
+     * The default locale to fall back to when translations are missing
+     */
+    readonly defaultLocale: SupportedLanguage;
+    /**
+     * Array of locales supported by the application
+     */
+    readonly supportedLocales: readonly SupportedLanguage[];
+    /**
+     * Optional locale to use if translation is missing in the current locale
+     */
+    readonly fallbackLocale?: SupportedLanguage;
+    /**
+     * Settings for extracting translation keys from source code
+     */
+    readonly extraction?: {
+        /**
+         * File patterns to search for translation keys
+         */
+        readonly patterns: readonly string[];
+        /**
+         * Function names that should be treated as translation functions
+         */
+        readonly functions: readonly string[];
+        /**
+         * Component names that should be treated as translation components
+         */
+        readonly components: readonly string[];
+        /**
+         * Directory where extracted translation files should be saved
+         */
+        readonly outputDir: string;
+        /**
+         * Whether to split extracted translations by namespace into separate files
+         */
+        readonly shouldSplitByNamespace: boolean;
+    };
+    /**
+     * Optional list of translation namespaces to load
+     */
+    readonly namespaces?: readonly string[];
+    /**
+     * Interpolation settings for variable replacement in translations
+     */
+    readonly interpolation?: {
+        /**
+         * Whether to escape interpolation values to prevent XSS attacks
+         */
+        readonly shouldEscapeValue?: boolean;
+        /**
+         * Prefix for interpolation variables (default: '{{')
+         */
+        readonly prefix?: string;
+        /**
+         * Suffix for interpolation variables (default: '}}')
+         */
+        readonly suffix?: string;
+    };
+    /**
+     * Loading strategy for translations
+     */
+    readonly loading?: {
+        /**
+         * Whether to load all translations at once ('eager') or on-demand ('lazy')
+         */
+        readonly strategy: 'lazy' | 'eager';
+        /**
+         * Whether to use fallback locale when translation is missing
+         */
+        readonly shouldUseFallback?: boolean;
+    };
+    /**
+     * Validation settings for translation keys
+     */
+    readonly validation?: {
+        /**
+         * Whether to throw errors for missing translation keys (strict mode)
+         */
+        readonly isStrict?: boolean;
+        /**
+         * Whether to show warnings for missing translation keys
+         */
+        readonly shouldWarnOnMissingKeys?: boolean;
+    };
+}
+/**
+ * Represents a translation key, including namespace, key, defaultValue, and interpolation options.
+ */
+export interface TranslationKey {
+    /**
+     * The namespace this translation key belongs to (e.g., 'common', 'errors')
+     */
+    readonly namespace: string;
+    /**
+     * The specific translation key within the namespace (e.g., 'hello', 'notFound')
+     */
+    readonly key: string;
+    /**
+     * Default value to use if translation is missing
+     */
+    readonly defaultValue?: string;
+    /**
+     * Interpolation variables to replace in the translation
+     */
+    readonly interpolation?: Record<string, string>;
+}
+/**
+ * Options for translation functions, including default value, interpolation args, locale override, and fallback flag.
+ */
+export interface TranslationOptions {
+    /**
+     * Default value to use if translation is missing
+     */
+    readonly defaultValue?: string;
+    /**
+     * Arguments to interpolate into the translation string
+     */
+    readonly args?: Record<string, string>;
+    /**
+     * Interpolation variables to replace in the translation
+     */
+    readonly interpolation?: Record<string, string>;
+    /**
+     * Override the current locale for this translation
+     */
+    readonly lang?: string;
+    /**
+     * Whether to use fallback locale if translation is missing
+     */
+    readonly shouldUseFallback?: boolean;
+}
+/**
+ * Defines methods available on translation service implementations.
+ */
+export interface Translator {
+    /**
+     * Translate a key to the current locale
+     */
+    readonly t: (key: TranslationKeys<TranslationResources>, options?: TranslationOptions) => string;
+    /**
+     * Translate a key within a specific namespace
+     */
+    readonly tNamespace: (namespace: string, key: TranslationKeys<TranslationResources>, options?: TranslationOptions) => string;
+    /**
+     * Change the current locale
+     */
+    readonly changeLocale: (locale: SupportedLanguage) => void;
+    /**
+     * Get the current locale
+     */
+    readonly getCurrentLocale: () => string;
+    /**
+     * Check if a translation key exists for the given locale
+     */
+    readonly hasTranslation: (key: string, locale?: string) => boolean;
+    /**
+     * Add a new namespace with translations
+     */
+    readonly addNamespace: (namespace: string, translations: Record<string, string>) => void;
+}
+/**
+ * Command-line interface options for extracting translation keys from source code.
+ * @description These types define the configuration options for the CLI tool that
+ * automatically extracts translation keys from source files and generates translation files.
+ */
+export interface ExtractOptions {
+    /**
+     * File pattern to search for translation keys
+     */
+    readonly pattern: string;
+    /**
+     * Output directory for extracted translation files
+     */
+    readonly output: string;
+    /**
+     * Whether to split extracted translations by namespace
+     */
+    readonly shouldSplitByNamespace: boolean;
+    /**
+     * Whether to update existing translation files
+     */
+    readonly shouldUpdate: boolean;
+    /**
+     * Whether to perform a dry run without writing files
+     */
+    readonly shouldDryRun: boolean;
+}
+/**
+ * Pluralization test cases for validating translation pluralization rules.
+ * @description These types define the structure for testing pluralization functionality
+ * across different languages, ensuring correct plural forms are used based on numeric values.
+ */
+/**
+ * Represents a single test case for pluralization validation.
+ * @description Defines a numeric value and its expected translation string
+ * to test pluralization rules in different languages.
+ */
+export interface PluralizationValueCase {
+    /**
+     * The numeric value to test pluralization against
+     */
+    readonly value: number;
+    /**
+     * The expected translation string for this value
+     */
+    readonly expected: string;
+}
+/**
+ * Represents a complete set of pluralization test cases for a specific language.
+ * @description Groups multiple pluralization value cases together for a single language,
+ * allowing comprehensive testing of pluralization rules across different numeric values.
+ */
+export interface PluralizationCase {
+    /**
+     * The language code for this pluralization case
+     */
+    readonly lang: SupportedLanguage;
+    /**
+     * Array of value cases to test pluralization rules
+     */
+    readonly values: readonly PluralizationValueCase[];
+}
+/**
+ * Date formatting test cases for validating locale-specific date formatting.
+ * @description These types define the structure for testing date formatting functionality
+ * across different languages and locales.
+ */
+/**
+ * Represents a test case for date formatting validation.
+ * @description Defines a language and its expected formatted date string
+ * to test date formatting rules in different locales.
+ */
+export interface DateCase {
+    /**
+     * The language code for this date formatting case
+     */
+    readonly lang: SupportedLanguage;
+    /**
+     * The expected formatted date string
+     */
+    readonly expected: string;
+}
+/**
+ * Number formatting test cases for validating locale-specific number formatting.
+ * @description These types define the structure for testing number formatting functionality
+ * across different languages and locales.
+ */
+/**
+ * Represents a test case for number formatting validation.
+ * @description Defines a language and its expected formatted number string
+ * to test number formatting rules in different locales.
+ */
+export interface NumberCase {
+    /**
+     * The language code for this number formatting case
+     */
+    readonly lang: SupportedLanguage;
+    /**
+     * The expected formatted number string
+     */
+    readonly expected: string;
+}
+/**
+ * Currency formatting test cases for validating locale-specific currency formatting.
+ * @description These types define the structure for testing currency formatting functionality
+ * across different languages and locales, including currency symbols and formatting options.
+ */
+/**
+ * Represents a test case for currency formatting validation.
+ * @description Defines a language, expected formatted currency string, and formatting options
+ * to test currency formatting rules in different locales.
+ */
+export interface CurrencyCase {
+    /**
+     * The language code for this currency formatting case
+     */
+    readonly lang: SupportedLanguage;
+    /**
+     * The expected formatted currency string
+     */
+    readonly expected: string;
+    /**
+     * NumberFormat options for currency formatting
+     */
+    readonly options: Intl.NumberFormatOptions;
+}
+export {};

package/dist/ui/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/web3/enums.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Enum representing supported EVM-compatible blockchain networks by their numeric chain IDs.
+ * @description These IDs are used to identify the specific network when interacting with wallets or smart contracts.
+ * @see https://chainlist.org for reference chain IDs
+ */
+export declare const CHAIN_ID: {
+    readonly EthereumMainnet: 1;
+    readonly EthereumSepolia: 11155111;
+    readonly Optimism: 10;
+    readonly OptimismSepolia: 11155420;
+    readonly Arbitrum: 42161;
+    readonly ArbitrumSepolia: 421614;
+    readonly Polygon: 137;
+    readonly PolygonAmoy: 80002;
+    readonly Base: 8453;
+    readonly BaseSepolia: 84532;
+};

package/dist/web3/index.d.ts

@@ -0,0 +1,2 @@
+export * from './enums';
+export type * from './types';

package/dist/web3/types.d.ts

@@ -0,0 +1,63 @@
+import type { CHAIN_ID } from './enums';
+/**
+ * Defines the configuration structure for an EVM-compatible blockchain network.
+ * @description This is commonly used for wallet integration, chain switching, and displaying metadata such as currency and explorer links.
+ */
+export interface NetworkConfig {
+    /**
+     * Numeric chain ID of the blockchain network.
+     * @description Should match the value from {@link typeof CHAIN_ID}.
+     * @example 137 // Polygon Mainnet
+     */
+    readonly chainId: typeof CHAIN_ID;
+    /**
+     * @description Full name of the network.
+     * @example "Polygon"
+     */
+    readonly name: string;
+    /**
+     * @description Short, user-friendly name for display purposes.
+     * @example "MATIC"
+     */
+    readonly shortName: string;
+    /**
+     * Native currency used on the network for fees and balances.
+     */
+    readonly nativeCurrency: {
+        /**
+         * @description Full name of the native currency.
+         * @example "Matic"
+         */
+        readonly name: string;
+        /**
+         * @description Symbol of the currency used in wallet UIs.
+         * @example "MATIC"
+         */
+        readonly symbol: string;
+        /**
+         * @description Number of decimal places used by the currency.
+         * @example 18
+         */
+        readonly decimals: number;
+    };
+    /**
+     * @description List of public RPC endpoints used to communicate with the blockchain.
+     * @example ["https://polygon-rpc.com"]
+     */
+    readonly rpcUrls: readonly string[];
+    /**
+     * @description List of block explorer base URLs for viewing transactions and contracts.
+     * @example ["https://polygonscan.com"]
+     */
+    readonly blockExplorerUrls: readonly string[];
+    /**
+     * @description Optional icon URL for the network, used in UIs.
+     * @example "https://example.com/icons/polygon.svg"
+     */
+    readonly iconUrl?: string;
+    /**
+     * @description Flag indicating if the network is a testnet.
+     * @example true
+     */
+    readonly isTestnet: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",
@@ -105,7 +105,7 @@
   "scripts": {
     "build": "pnpm clean && pnpm build:js && pnpm build:types",
     "build:js": "tsup",
-    "build:types": "tsc -p tsconfig.build.json",
+    "build:types": "tsc src/index.ts --emitDeclarationOnly --esModuleInterop --outDir dist --declaration --skipLibCheck",
     "build:watch": "tsup --watch",
     "dev": "tsup --watch",
     "lint": "eslint ./src",