@cranberry-money/shared-utils 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# @myportfolio/shared-utils
+
+Shared utility functions for the MyPortfolio platform, supporting both web (Blueberry) and mobile (Blackberry) applications.
+
+## Installation
+
+```bash
+npm install @myportfolio/shared-utils
+```
+
+## Usage
+
+```typescript
+import { 
+  formatCurrency, 
+  formatDate, 
+  hasActiveFilters,
+  truncateText 
+} from '@myportfolio/shared-utils';
+
+// Currency formatting
+const amount = formatCurrency(1234.56); // "1,234.56"
+
+// Date formatting
+const date = formatDate('2024-01-15T10:30:00Z'); // "1/15/2024"
+
+// Filter utilities
+const hasFilters = hasActiveFilters({ name: 'Apple', category: '', page: 1 }); // true
+
+// Text utilities
+const short = truncateText('This is a very long text', 10); // "This is a..."
+```
+
+## Available Utilities
+
+### Formatters
+
+#### Currency (`formatters/currency.ts`)
+- `formatCurrency(value)` - Format number with commas and 2 decimals
+- `parseCurrencyInput(value)` - Parse currency string to number
+- `formatCurrencyWithCode(value, code, locale, minDigits, maxDigits)` - Format with currency code
+- `formatDefaultCurrency(value, minDigits, maxDigits)` - Format with default currency (AUD)
+
+#### Dates (`formatters/dates.ts`)
+- `formatDate(dateString, fallback)` - Format ISO date to localized date
+- `formatShortDate(dateString, locale)` - Format to short date (e.g., "Jan 15")
+- `formatTime(dateString, locale)` - Format to 24-hour time
+- `formatDateTime(dateString, locale)` - Format to "Jan 15 14:30"
+
+#### Numbers (`formatters/numbers.ts`)
+- `formatShares(shares, locale)` - Format share quantities (no decimals)
+
+### Helpers
+
+#### Filters (`helpers/filters.ts`)
+- `hasActiveFilters<T>(filters, excludeFields)` - Check if any filters are active
+- `countActiveFilters<T>(filters, excludeFields)` - Count active filters
+- `clearAllFilters<T>(filters, preserveFields)` - Clear all filter values
+- `updateFilters<T>(currentFilters, updates)` - Type-safe filter updates
+
+#### Text (`helpers/text.ts`)
+- `truncateText(text, maxLength)` - Truncate text with ellipsis
+
+## Platform Compatibility
+
+This package is designed to work across:
+- Web applications (React) - Direct use of utility functions
+- Mobile applications (React Native) - Platform-agnostic implementations
+- Node.js environments - For server-side utility needs
+
+### Platform-Specific Considerations
+
+#### Date Formatting
+The date formatters use `Intl.DateTimeFormat` and `toLocaleDateString` which work consistently across web and React Native platforms.
+
+#### Currency Formatting
+Currency formatters use `Intl.NumberFormat` which provides consistent formatting across platforms with proper locale support.
+
+#### Filter Utilities
+Filter utilities are completely platform-agnostic and work with any TypeScript object structure.
+
+## Examples
+
+### Currency Formatting
+```typescript
+import { formatCurrency, formatCurrencyWithCode } from '@myportfolio/shared-utils';
+
+// Basic formatting
+formatCurrency(1234.56); // "1,234.56"
+formatCurrency("1234.56"); // "1,234.56"
+
+// With currency code
+formatCurrencyWithCode(1234.56, 'USD', 'en-US', 2, 2); // "$1,234.56"
+formatCurrencyWithCode(1234.56, 'AUD', 'en-AU', 0, 0); // "A$1,235"
+```
+
+### Filter Management
+```typescript
+import { hasActiveFilters, countActiveFilters, clearAllFilters } from '@myportfolio/shared-utils';
+
+const filters = {
+  searchQuery: 'apple',
+  category: 'technology',
+  minPrice: 100,
+  maxPrice: null,
+  tags: [],
+};
+
+// Check for active filters (excluding searchQuery by default)
+hasActiveFilters(filters); // true (category and minPrice are active)
+
+// Count active filters
+countActiveFilters(filters); // 2 (category and minPrice)
+
+// Clear all filters while preserving searchQuery
+const cleared = clearAllFilters(filters, ['searchQuery']);
+// Result: { searchQuery: 'apple' }
+```
+
+### Date Formatting
+```typescript
+import { formatDate, formatDateTime, formatShortDate } from '@myportfolio/shared-utils';
+
+const isoDate = '2024-01-15T14:30:00Z';
+
+formatDate(isoDate); // "1/15/2024"
+formatShortDate(isoDate); // "Jan 15"  
+formatDateTime(isoDate); // "Jan 15 14:30"
+```
+
+## Development
+
+```bash
+# Build the package
+npm run build
+
+# Watch for changes
+npm run dev
+
+# Type check
+npm run typecheck
+```
+
+## Dependencies
+
+- `@myportfolio/shared-constants` - For currency and formatting constants
+
+## License
+
+MIT

package/dist/formatters/currency.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Formats a number as currency with commas and 2 decimal places
+ */
+export declare const formatCurrency: (value: number | string) => string;
+/**
+ * Parses a currency string input into a number
+ * @param value - Currency string to parse
+ * @returns Parsed number value (or 0 if invalid)
+ */
+export declare const parseCurrencyInput: (value: string) => number;
+/**
+ * Formats a number as currency with specific currency code and locale
+ * @param value - Number to format
+ * @param currencyCode - ISO 4217 currency code (default: DEFAULT_CURRENCY)
+ * @param locale - Locale for formatting (default: 'en-AU')
+ * @param minimumFractionDigits - Minimum decimal places (default: 0)
+ * @param maximumFractionDigits - Maximum decimal places (default: 0)
+ * @returns Formatted currency string
+ */
+export declare const formatCurrencyWithCode: (value: number, currencyCode?: string, locale?: string, minimumFractionDigits?: number, maximumFractionDigits?: number) => string;
+/**
+ * Convenience function to format currency with the default currency (AUD)
+ * @param value - Number to format
+ * @param minimumFractionDigits - Minimum decimal places (default: 0)
+ * @param maximumFractionDigits - Maximum decimal places (default: 0)
+ * @returns Formatted currency string with default currency
+ */
+export declare const formatDefaultCurrency: (value: number, minimumFractionDigits?: number, maximumFractionDigits?: number) => string;
+//# sourceMappingURL=currency.d.ts.map

package/dist/formatters/currency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../../src/formatters/currency.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,GAAG,MAAM,KAAG,MAWvD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAOlD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,MAAM,EACb,eAAc,MAAyB,EACvC,SAAQ,MAAgB,EACxB,wBAAuB,MAAU,EACjC,wBAAuB,MAAU,KAChC,MASF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,MAAM,EACb,wBAAuB,MAAU,EACjC,wBAAuB,MAAU,KAChC,MAEF,CAAC"}

package/dist/formatters/currency.js

@@ -0,0 +1,55 @@
+import { DEFAULT_CURRENCY } from '@myportfolio/shared-constants';
+/**
+ * Formats a number as currency with commas and 2 decimal places
+ */
+export const formatCurrency = (value) => {
+    if (!value && value !== 0)
+        return '';
+    const numValue = typeof value === 'string' ? parseFloat(value) : value;
+    if (isNaN(numValue))
+        return '';
+    return numValue.toLocaleString('en-AU', {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    });
+};
+/**
+ * Parses a currency string input into a number
+ * @param value - Currency string to parse
+ * @returns Parsed number value (or 0 if invalid)
+ */
+export const parseCurrencyInput = (value) => {
+    const cleanValue = value.replace(/[^0-9.]/g, '');
+    const parts = cleanValue.split('.');
+    const formattedValue = parts[0] + (parts.length > 1 ? '.' + parts[1].slice(0, 2) : '');
+    return parseFloat(formattedValue) || 0;
+};
+/**
+ * Formats a number as currency with specific currency code and locale
+ * @param value - Number to format
+ * @param currencyCode - ISO 4217 currency code (default: DEFAULT_CURRENCY)
+ * @param locale - Locale for formatting (default: 'en-AU')
+ * @param minimumFractionDigits - Minimum decimal places (default: 0)
+ * @param maximumFractionDigits - Maximum decimal places (default: 0)
+ * @returns Formatted currency string
+ */
+export const formatCurrencyWithCode = (value, currencyCode = DEFAULT_CURRENCY, locale = 'en-AU', minimumFractionDigits = 0, maximumFractionDigits = 0) => {
+    if (value == null || isNaN(value))
+        return '';
+    return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency: currencyCode,
+        minimumFractionDigits,
+        maximumFractionDigits,
+    }).format(value);
+};
+/**
+ * Convenience function to format currency with the default currency (AUD)
+ * @param value - Number to format
+ * @param minimumFractionDigits - Minimum decimal places (default: 0)
+ * @param maximumFractionDigits - Maximum decimal places (default: 0)
+ * @returns Formatted currency string with default currency
+ */
+export const formatDefaultCurrency = (value, minimumFractionDigits = 0, maximumFractionDigits = 0) => {
+    return formatCurrencyWithCode(value, DEFAULT_CURRENCY, 'en-AU', minimumFractionDigits, maximumFractionDigits);
+};

package/dist/formatters/dates.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Formats a date string to a localized date
+ * @param dateString - ISO date string or null
+ * @param fallback - Fallback text when date is null (default: 'No expiry')
+ * @returns Formatted date string
+ */
+export declare const formatDate: (dateString: string | null, fallback?: string) => string;
+/**
+ * Formats a date string to a short date format (e.g., "Jan 15")
+ */
+export declare const formatShortDate: (dateString: string, locale?: string) => string;
+/**
+ * Formats a date string to a time format (24-hour)
+ */
+export declare const formatTime: (dateString: string, locale?: string) => string;
+/**
+ * Formats a date string to a combined short date and time format
+ * @param dateString - ISO date string
+ * @param locale - Locale for formatting (default: 'en-AU')
+ * @returns Formatted string like "Jan 15 14:30"
+ */
+export declare const formatDateTime: (dateString: string, locale?: string) => string;
+//# sourceMappingURL=dates.d.ts.map

package/dist/formatters/dates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../../src/formatters/dates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,YAAY,MAAM,GAAG,IAAI,EAAE,WAAU,MAAoB,KAAG,MAGtF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,YAAY,MAAM,EAAE,SAAQ,MAAgB,KAAG,MAM9E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,YAAY,MAAM,EAAE,SAAQ,MAAgB,KAAG,MAMzE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,YAAY,MAAM,EAAE,SAAQ,MAAgB,KAAG,MAY7E,CAAC"}

package/dist/formatters/dates.js

@@ -0,0 +1,50 @@
+/**
+ * Formats a date string to a localized date
+ * @param dateString - ISO date string or null
+ * @param fallback - Fallback text when date is null (default: 'No expiry')
+ * @returns Formatted date string
+ */
+export const formatDate = (dateString, fallback = 'No expiry') => {
+    if (!dateString)
+        return fallback;
+    return new Date(dateString).toLocaleDateString();
+};
+/**
+ * Formats a date string to a short date format (e.g., "Jan 15")
+ */
+export const formatShortDate = (dateString, locale = 'en-AU') => {
+    const date = new Date(dateString);
+    return date.toLocaleDateString(locale, {
+        month: 'short',
+        day: 'numeric',
+    });
+};
+/**
+ * Formats a date string to a time format (24-hour)
+ */
+export const formatTime = (dateString, locale = 'en-AU') => {
+    return new Date(dateString).toLocaleTimeString(locale, {
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false,
+    });
+};
+/**
+ * Formats a date string to a combined short date and time format
+ * @param dateString - ISO date string
+ * @param locale - Locale for formatting (default: 'en-AU')
+ * @returns Formatted string like "Jan 15 14:30"
+ */
+export const formatDateTime = (dateString, locale = 'en-AU') => {
+    const date = new Date(dateString);
+    const shortDate = date.toLocaleDateString(locale, {
+        month: 'short',
+        day: 'numeric',
+    });
+    const time = date.toLocaleTimeString(locale, {
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false,
+    });
+    return `${shortDate} ${time}`;
+};

package/dist/formatters/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Centralized export of formatting utilities
+ */
+export * from './currency';
+export * from './dates';
+export * from './numbers';
+//# sourceMappingURL=index.d.ts.map

package/dist/formatters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formatters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/dist/formatters/index.js

@@ -0,0 +1,6 @@
+/**
+ * Centralized export of formatting utilities
+ */
+export * from './currency';
+export * from './dates';
+export * from './numbers';

package/dist/formatters/numbers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats a number for displaying share quantities (no decimals)
+ * @param shares - Number of shares to format
+ * @param locale - Locale for formatting (default: 'en-AU')
+ * @returns Formatted shares string with commas as thousands separators
+ */
+export declare const formatShares: (shares: number, locale?: string) => string;
+//# sourceMappingURL=numbers.d.ts.map

package/dist/formatters/numbers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../../src/formatters/numbers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,SAAQ,MAAgB,KAAG,MAKvE,CAAC"}

package/dist/formatters/numbers.js

@@ -0,0 +1,12 @@
+/**
+ * Formats a number for displaying share quantities (no decimals)
+ * @param shares - Number of shares to format
+ * @param locale - Locale for formatting (default: 'en-AU')
+ * @returns Formatted shares string with commas as thousands separators
+ */
+export const formatShares = (shares, locale = 'en-AU') => {
+    return new Intl.NumberFormat(locale, {
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 0,
+    }).format(shares);
+};

package/dist/helpers/filters.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared utility functions for trading filter operations
+ * Addresses filter utility logic duplications across trading pages
+ */
+/**
+ * Generic function to check if any filters are active
+ * Replaces hasActiveTradeFilters, hasActiveTransactionFilters, hasActiveInstrumentFilters
+ */
+export declare function hasActiveFilters<T extends Record<string, unknown>>(filters: T, excludeFields?: (keyof T)[]): boolean;
+/**
+ * Generic function to count active filters
+ * Replaces countActiveTradeFilters, countActiveTransactionFilters, countActiveInstrumentFilters
+ */
+export declare function countActiveFilters<T extends Record<string, unknown>>(filters: T, excludeFields?: (keyof T)[]): number;
+/**
+ * Generic function to clear all filters
+ * Maintains type safety while resetting filter state
+ */
+export declare function clearAllFilters<T extends Record<string, unknown>>(filters: T, preserveFields?: (keyof T)[]): Partial<T>;
+/**
+ * Type-safe filter update helper
+ * Ensures only valid filter fields can be updated
+ */
+export declare function updateFilters<T extends Record<string, unknown>>(currentFilters: T, updates: Partial<T>): T;
+//# sourceMappingURL=filters.d.ts.map

package/dist/helpers/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/helpers/filters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,OAAO,EAAE,CAAC,EACV,aAAa,GAAE,CAAC,MAAM,CAAC,CAAC,EAAoB,GAC3C,OAAO,CAOT;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,OAAO,EAAE,CAAC,EACV,aAAa,GAAE,CAAC,MAAM,CAAC,CAAC,EAAoB,GAC3C,MAAM,CAOR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,OAAO,EAAE,CAAC,EACV,cAAc,GAAE,CAAC,MAAM,CAAC,CAAC,EAAO,GAC/B,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAE1G"}

package/dist/helpers/filters.js

@@ -0,0 +1,41 @@
+/**
+ * Shared utility functions for trading filter operations
+ * Addresses filter utility logic duplications across trading pages
+ */
+/**
+ * Generic function to check if any filters are active
+ * Replaces hasActiveTradeFilters, hasActiveTransactionFilters, hasActiveInstrumentFilters
+ */
+export function hasActiveFilters(filters, excludeFields = ['searchQuery']) {
+    const relevantEntries = Object.entries(filters).filter(([key]) => !excludeFields.includes(key));
+    return relevantEntries.some(([, value]) => value !== undefined && value !== null && value !== '' && !(Array.isArray(value) && value.length === 0));
+}
+/**
+ * Generic function to count active filters
+ * Replaces countActiveTradeFilters, countActiveTransactionFilters, countActiveInstrumentFilters
+ */
+export function countActiveFilters(filters, excludeFields = ['searchQuery']) {
+    const relevantEntries = Object.entries(filters).filter(([key]) => !excludeFields.includes(key));
+    return relevantEntries.filter(([, value]) => value !== undefined && value !== null && value !== '' && !(Array.isArray(value) && value.length === 0)).length;
+}
+/**
+ * Generic function to clear all filters
+ * Maintains type safety while resetting filter state
+ */
+export function clearAllFilters(filters, preserveFields = []) {
+    const clearedFilters = {};
+    // Preserve specified fields
+    preserveFields.forEach((field) => {
+        if (field in filters) {
+            clearedFilters[field] = filters[field];
+        }
+    });
+    return clearedFilters;
+}
+/**
+ * Type-safe filter update helper
+ * Ensures only valid filter fields can be updated
+ */
+export function updateFilters(currentFilters, updates) {
+    return { ...currentFilters, ...updates };
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Centralized export of helper utilities
+ */
+export * from './filters';
+export * from './text';
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC"}

package/dist/helpers/index.js

@@ -0,0 +1,5 @@
+/**
+ * Centralized export of helper utilities
+ */
+export * from './filters';
+export * from './text';

package/dist/helpers/text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Truncates text to a specified maximum length and adds ellipsis if needed
+ * @param text - The text to truncate
+ * @param maxLength - The maximum length of the text (default: 30)
+ * @returns The truncated text with ellipsis if it exceeds maxLength
+ */
+export declare const truncateText: (text: string, maxLength?: number) => string;
+//# sourceMappingURL=text.d.ts.map

package/dist/helpers/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/helpers/text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,YAAW,MAAW,KAAG,MAGnE,CAAC"}

package/dist/helpers/text.js

@@ -0,0 +1,11 @@
+/**
+ * Truncates text to a specified maximum length and adds ellipsis if needed
+ * @param text - The text to truncate
+ * @param maxLength - The maximum length of the text (default: 30)
+ * @returns The truncated text with ellipsis if it exceeds maxLength
+ */
+export const truncateText = (text, maxLength = 30) => {
+    if (text.length <= maxLength)
+        return text;
+    return `${text.substring(0, maxLength)}...`;
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Centralized export of all shared utilities
+ */
+export * from './formatters';
+export * from './helpers';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * Centralized export of all shared utilities
+ */
+export * from './formatters';
+export * from './helpers';

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cranberry-money/shared-utils",
+  "version": "1.0.0",
+  "description": "Shared utility functions for MyPortfolio platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@cranberry-money/shared-constants": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "keywords": [
+    "typescript",
+    "utilities",
+    "shared",
+    "portfolio"
+  ],
+  "author": "MyPortfolio Team",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/cranberry.git",
+    "directory": "packages/shared-utils"
+  }
+}