typetify 2.1.0 → 2.4.0

package/dist/storage/index.d.mts

@@ -0,0 +1,197 @@
+/**
+ * Type-safe storage wrapper with serialization.
+ *
+ * @example
+ * // Create typed storage
+ * interface UserPrefs {
+ *   theme: 'light' | 'dark';
+ *   language: string;
+ *   notifications: boolean;
+ * }
+ *
+ * const prefs = createStorage<UserPrefs>('user-prefs', {
+ *   storage: localStorage
+ * });
+ *
+ * prefs.set({ theme: 'dark', language: 'en', notifications: true });
+ * const theme = prefs.get()?.theme; // 'dark' | undefined
+ *
+ * @example
+ * // With default value
+ * const settings = createStorage('settings', {
+ *   storage: localStorage,
+ *   defaultValue: { volume: 50 }
+ * });
+ *
+ * @example
+ * // Session storage
+ * const tempData = createStorage('temp', {
+ *   storage: sessionStorage
+ * });
+ */
+interface StorageOptions<T> {
+    storage: Storage;
+    defaultValue?: T;
+    serializer?: {
+        stringify: (value: T) => string;
+        parse: (value: string) => T;
+    };
+}
+interface TypedStorage<T> {
+    get(): T | null;
+    set(value: T): void;
+    remove(): void;
+    clear(): void;
+    has(): boolean;
+}
+declare function createStorage<T>(key: string, options: StorageOptions<T>): TypedStorage<T>;
+/**
+ * Creates a storage instance with localStorage.
+ *
+ * @example
+ * const userPrefs = localStorageTyped<UserPrefs>('prefs');
+ * userPrefs.set({ theme: 'dark' });
+ */
+declare function localStorageTyped<T>(key: string, defaultValue?: T): TypedStorage<T>;
+/**
+ * Creates a storage instance with sessionStorage.
+ *
+ * @example
+ * const tempData = sessionStorageTyped<TempData>('temp');
+ * tempData.set({ token: 'abc123' });
+ */
+declare function sessionStorageTyped<T>(key: string, defaultValue?: T): TypedStorage<T>;
+
+/**
+ * Storage wrapper that adds expiration to stored values.
+ *
+ * @example
+ * // Store with 1 hour expiry
+ * const cache = withExpiry<User>('user-cache', {
+ *   storage: localStorage,
+ *   ttl: 60 * 60 * 1000 // 1 hour in ms
+ * });
+ *
+ * cache.set(user);
+ * const cached = cache.get(); // null after 1 hour
+ *
+ * @example
+ * // Check if expired
+ * if (cache.isExpired()) {
+ *   cache.remove();
+ *   fetchFreshData();
+ * }
+ *
+ * @example
+ * // API response caching
+ * const apiCache = withExpiry<ApiResponse>('api-cache', {
+ *   storage: sessionStorage,
+ *   ttl: 5 * 60 * 1000 // 5 minutes
+ * });
+ */
+interface ExpiryStorageOptions {
+    storage: Storage;
+    ttl: number;
+}
+interface ExpiryStorage<T> {
+    get(): T | null;
+    set(value: T): void;
+    remove(): void;
+    isExpired(): boolean;
+    getExpiry(): number | null;
+}
+declare function withExpiry<T>(key: string, options: ExpiryStorageOptions): ExpiryStorage<T>;
+
+/**
+ * In-memory storage implementation (useful for SSR/testing).
+ *
+ * @example
+ * // Use in Node.js or SSR
+ * const storage = createMemoryStorage();
+ * storage.setItem('key', 'value');
+ * storage.getItem('key'); // => 'value'
+ *
+ * @example
+ * // Fallback when localStorage is not available
+ * const storage = typeof window !== 'undefined'
+ *   ? localStorage
+ *   : createMemoryStorage();
+ *
+ * @example
+ * // Testing
+ * const mockStorage = createMemoryStorage();
+ * const store = createStorage('test', { storage: mockStorage });
+ */
+declare function createMemoryStorage(): Storage;
+
+/**
+ * Cookie options for setting cookies.
+ */
+interface CookieOptions {
+    expires?: Date | number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * Gets a cookie value by name.
+ *
+ * @example
+ * const token = getCookie('auth_token');
+ * if (token) {
+ *   authenticate(token);
+ * }
+ *
+ * @example
+ * // Returns null if not found
+ * const missing = getCookie('nonexistent'); // => null
+ */
+declare function getCookie(name: string): string | null;
+/**
+ * Sets a cookie with options.
+ *
+ * @example
+ * // Simple cookie
+ * setCookie('user_id', '123');
+ *
+ * @example
+ * // With expiration (7 days)
+ * setCookie('session', 'abc', { expires: 7 });
+ *
+ * @example
+ * // Secure cookie
+ * setCookie('auth_token', token, {
+ *   expires: 30,
+ *   secure: true,
+ *   sameSite: 'Strict',
+ *   path: '/'
+ * });
+ *
+ * @example
+ * // Session cookie (expires when browser closes)
+ * setCookie('temp', 'value');
+ */
+declare function setCookie(name: string, value: string, options?: CookieOptions): void;
+/**
+ * Removes a cookie by name.
+ *
+ * @example
+ * removeCookie('session');
+ *
+ * @example
+ * // Remove with specific path
+ * removeCookie('token', { path: '/admin' });
+ */
+declare function removeCookie(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+/**
+ * Checks if a cookie exists.
+ *
+ * @example
+ * if (hasCookie('auth_token')) {
+ *   console.log('User is authenticated');
+ * }
+ */
+declare function hasCookie(name: string): boolean;
+
+export { type CookieOptions, type ExpiryStorage, type ExpiryStorageOptions, type StorageOptions, type TypedStorage, createMemoryStorage, createStorage, getCookie, hasCookie, localStorageTyped, removeCookie, sessionStorageTyped, setCookie, withExpiry };

package/dist/storage/index.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Type-safe storage wrapper with serialization.
+ *
+ * @example
+ * // Create typed storage
+ * interface UserPrefs {
+ *   theme: 'light' | 'dark';
+ *   language: string;
+ *   notifications: boolean;
+ * }
+ *
+ * const prefs = createStorage<UserPrefs>('user-prefs', {
+ *   storage: localStorage
+ * });
+ *
+ * prefs.set({ theme: 'dark', language: 'en', notifications: true });
+ * const theme = prefs.get()?.theme; // 'dark' | undefined
+ *
+ * @example
+ * // With default value
+ * const settings = createStorage('settings', {
+ *   storage: localStorage,
+ *   defaultValue: { volume: 50 }
+ * });
+ *
+ * @example
+ * // Session storage
+ * const tempData = createStorage('temp', {
+ *   storage: sessionStorage
+ * });
+ */
+interface StorageOptions<T> {
+    storage: Storage;
+    defaultValue?: T;
+    serializer?: {
+        stringify: (value: T) => string;
+        parse: (value: string) => T;
+    };
+}
+interface TypedStorage<T> {
+    get(): T | null;
+    set(value: T): void;
+    remove(): void;
+    clear(): void;
+    has(): boolean;
+}
+declare function createStorage<T>(key: string, options: StorageOptions<T>): TypedStorage<T>;
+/**
+ * Creates a storage instance with localStorage.
+ *
+ * @example
+ * const userPrefs = localStorageTyped<UserPrefs>('prefs');
+ * userPrefs.set({ theme: 'dark' });
+ */
+declare function localStorageTyped<T>(key: string, defaultValue?: T): TypedStorage<T>;
+/**
+ * Creates a storage instance with sessionStorage.
+ *
+ * @example
+ * const tempData = sessionStorageTyped<TempData>('temp');
+ * tempData.set({ token: 'abc123' });
+ */
+declare function sessionStorageTyped<T>(key: string, defaultValue?: T): TypedStorage<T>;
+
+/**
+ * Storage wrapper that adds expiration to stored values.
+ *
+ * @example
+ * // Store with 1 hour expiry
+ * const cache = withExpiry<User>('user-cache', {
+ *   storage: localStorage,
+ *   ttl: 60 * 60 * 1000 // 1 hour in ms
+ * });
+ *
+ * cache.set(user);
+ * const cached = cache.get(); // null after 1 hour
+ *
+ * @example
+ * // Check if expired
+ * if (cache.isExpired()) {
+ *   cache.remove();
+ *   fetchFreshData();
+ * }
+ *
+ * @example
+ * // API response caching
+ * const apiCache = withExpiry<ApiResponse>('api-cache', {
+ *   storage: sessionStorage,
+ *   ttl: 5 * 60 * 1000 // 5 minutes
+ * });
+ */
+interface ExpiryStorageOptions {
+    storage: Storage;
+    ttl: number;
+}
+interface ExpiryStorage<T> {
+    get(): T | null;
+    set(value: T): void;
+    remove(): void;
+    isExpired(): boolean;
+    getExpiry(): number | null;
+}
+declare function withExpiry<T>(key: string, options: ExpiryStorageOptions): ExpiryStorage<T>;
+
+/**
+ * In-memory storage implementation (useful for SSR/testing).
+ *
+ * @example
+ * // Use in Node.js or SSR
+ * const storage = createMemoryStorage();
+ * storage.setItem('key', 'value');
+ * storage.getItem('key'); // => 'value'
+ *
+ * @example
+ * // Fallback when localStorage is not available
+ * const storage = typeof window !== 'undefined'
+ *   ? localStorage
+ *   : createMemoryStorage();
+ *
+ * @example
+ * // Testing
+ * const mockStorage = createMemoryStorage();
+ * const store = createStorage('test', { storage: mockStorage });
+ */
+declare function createMemoryStorage(): Storage;
+
+/**
+ * Cookie options for setting cookies.
+ */
+interface CookieOptions {
+    expires?: Date | number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * Gets a cookie value by name.
+ *
+ * @example
+ * const token = getCookie('auth_token');
+ * if (token) {
+ *   authenticate(token);
+ * }
+ *
+ * @example
+ * // Returns null if not found
+ * const missing = getCookie('nonexistent'); // => null
+ */
+declare function getCookie(name: string): string | null;
+/**
+ * Sets a cookie with options.
+ *
+ * @example
+ * // Simple cookie
+ * setCookie('user_id', '123');
+ *
+ * @example
+ * // With expiration (7 days)
+ * setCookie('session', 'abc', { expires: 7 });
+ *
+ * @example
+ * // Secure cookie
+ * setCookie('auth_token', token, {
+ *   expires: 30,
+ *   secure: true,
+ *   sameSite: 'Strict',
+ *   path: '/'
+ * });
+ *
+ * @example
+ * // Session cookie (expires when browser closes)
+ * setCookie('temp', 'value');
+ */
+declare function setCookie(name: string, value: string, options?: CookieOptions): void;
+/**
+ * Removes a cookie by name.
+ *
+ * @example
+ * removeCookie('session');
+ *
+ * @example
+ * // Remove with specific path
+ * removeCookie('token', { path: '/admin' });
+ */
+declare function removeCookie(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+/**
+ * Checks if a cookie exists.
+ *
+ * @example
+ * if (hasCookie('auth_token')) {
+ *   console.log('User is authenticated');
+ * }
+ */
+declare function hasCookie(name: string): boolean;
+
+export { type CookieOptions, type ExpiryStorage, type ExpiryStorageOptions, type StorageOptions, type TypedStorage, createMemoryStorage, createStorage, getCookie, hasCookie, localStorageTyped, removeCookie, sessionStorageTyped, setCookie, withExpiry };

package/dist/storage/index.js

@@ -0,0 +1 @@
+'use strict';var chunkF76ECQKE_js=require('../chunk-F76ECQKE.js');require('../chunk-WOT6VMZA.js');Object.defineProperty(exports,"createMemoryStorage",{enumerable:true,get:function(){return chunkF76ECQKE_js.e}});Object.defineProperty(exports,"createStorage",{enumerable:true,get:function(){return chunkF76ECQKE_js.a}});Object.defineProperty(exports,"getCookie",{enumerable:true,get:function(){return chunkF76ECQKE_js.f}});Object.defineProperty(exports,"hasCookie",{enumerable:true,get:function(){return chunkF76ECQKE_js.i}});Object.defineProperty(exports,"localStorageTyped",{enumerable:true,get:function(){return chunkF76ECQKE_js.b}});Object.defineProperty(exports,"removeCookie",{enumerable:true,get:function(){return chunkF76ECQKE_js.h}});Object.defineProperty(exports,"sessionStorageTyped",{enumerable:true,get:function(){return chunkF76ECQKE_js.c}});Object.defineProperty(exports,"setCookie",{enumerable:true,get:function(){return chunkF76ECQKE_js.g}});Object.defineProperty(exports,"withExpiry",{enumerable:true,get:function(){return chunkF76ECQKE_js.d}});

package/dist/storage/index.mjs

@@ -0,0 +1 @@
+export{e as createMemoryStorage,a as createStorage,f as getCookie,i as hasCookie,b as localStorageTyped,h as removeCookie,c as sessionStorageTyped,g as setCookie,d as withExpiry}from'../chunk-MB77QAOC.mjs';import'../chunk-JZXLCA2E.mjs';

package/dist/string/index.d.mts

@@ -99,4 +99,204 @@ declare function template(str: string, vars: Record<string, unknown>): string;
  */
 declare function words(str: string): string[];
 
-export { camelCase, capitalize, kebabCase, pascalCase, slugify, snakeCase, template, truncate, uncapitalize, words };
+/**
+ * Removes diacritical marks (accents) from a string.
+ * Converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters.
+ *
+ * @example
+ * // Remove French accents
+ * deburr('déjà vu')
+ * // => 'deja vu'
+ *
+ * @example
+ * // Remove German umlauts
+ * deburr('Müller')
+ * // => 'Muller'
+ *
+ * @example
+ * // Remove Spanish accents
+ * deburr('señor')
+ * // => 'senor'
+ *
+ * @example
+ * // Useful for search/filtering
+ * const users = ['José', 'François', 'Müller']
+ * const search = 'jose'
+ * users.filter(name => deburr(name).toLowerCase().includes(search))
+ * // => ['José']
+ *
+ * @example
+ * // Create URL-safe slugs
+ * deburr('Crème brûlée').toLowerCase().replace(/\s+/g, '-')
+ * // => 'creme-brulee'
+ */
+declare function deburr(str: string): string;
+
+/**
+ * Escapes HTML special characters to prevent XSS attacks.
+ * Converts &, <, >, ", and ' to their HTML entity equivalents.
+ *
+ * @example
+ * // Escape user input before rendering
+ * escape('<script>alert("xss")</script>')
+ * // => '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ *
+ * @example
+ * // Escape ampersands
+ * escape('Tom & Jerry')
+ * // => 'Tom &amp; Jerry'
+ *
+ * @example
+ * // Escape quotes in attributes
+ * escape('He said "Hello"')
+ * // => 'He said &quot;Hello&quot;'
+ *
+ * @example
+ * // Safe to use in innerHTML
+ * const userInput = '<img src=x onerror=alert(1)>'
+ * element.innerHTML = escape(userInput)
+ * // Renders as text, not as HTML
+ *
+ * @example
+ * // Escape single quotes
+ * escape("It's a test")
+ * // => 'It&#39;s a test'
+ */
+declare function escape(str: string): string;
+
+/**
+ * Converts HTML entities back to their corresponding characters.
+ * Inverse of escape().
+ *
+ * @example
+ * // Unescape HTML entities
+ * unescape('&lt;script&gt;')
+ * // => '<script>'
+ *
+ * @example
+ * // Unescape ampersands
+ * unescape('Tom &amp; Jerry')
+ * // => 'Tom & Jerry'
+ *
+ * @example
+ * // Unescape quotes
+ * unescape('He said &quot;Hello&quot;')
+ * // => 'He said "Hello"'
+ *
+ * @example
+ * // Parse escaped content from API
+ * const apiResponse = { title: 'Rock &amp; Roll' }
+ * unescape(apiResponse.title)
+ * // => 'Rock & Roll'
+ */
+declare function unescape(str: string): string;
+
+/**
+ * Escapes special RegExp characters in a string.
+ * Useful when building dynamic regular expressions from user input.
+ *
+ * @example
+ * // Escape special characters
+ * escapeRegExp('[lodash](https://lodash.com/)')
+ * // => '\\[lodash\\]\\(https://lodash\\.com/\\)'
+ *
+ * @example
+ * // Safe dynamic regex from user input
+ * const userSearch = 'price: $100'
+ * const regex = new RegExp(escapeRegExp(userSearch), 'i')
+ * regex.test('The price: $100 is final') // => true
+ *
+ * @example
+ * // Highlight search terms safely
+ * function highlightText(text: string, search: string) {
+ *   const escaped = escapeRegExp(search)
+ *   return text.replace(new RegExp(escaped, 'gi'), '<mark>$&</mark>')
+ * }
+ * highlightText('Hello (world)', '(world)')
+ * // => 'Hello <mark>(world)</mark>'
+ *
+ * @example
+ * // Build complex patterns safely
+ * const terms = ['C++', 'C#', '.NET']
+ * const pattern = terms.map(escapeRegExp).join('|')
+ * const regex = new RegExp(pattern, 'g')
+ * 'I know C++ and .NET'.match(regex)
+ * // => ['C++', '.NET']
+ */
+declare function escapeRegExp(str: string): string;
+
+/**
+ * Pads a string on both sides to reach the target length.
+ * If the padding length is odd, the extra character goes to the right.
+ *
+ * @example
+ * // Center text
+ * pad('hello', 11)
+ * // => '   hello   '
+ *
+ * @example
+ * // Custom padding character
+ * pad('5', 3, '0')
+ * // => '050'
+ *
+ * @example
+ * // Center with dashes
+ * pad('TITLE', 15, '-')
+ * // => '-----TITLE-----'
+ *
+ * @example
+ * // No padding if already long enough
+ * pad('hello', 3)
+ * // => 'hello'
+ */
+declare function pad(str: string, length: number, chars?: string): string;
+/**
+ * Pads a string on the left (start) to reach the target length.
+ *
+ * @example
+ * // Pad numbers with zeros
+ * padStart('5', 3, '0')
+ * // => '005'
+ *
+ * @example
+ * // Format time components
+ * padStart('9', 2, '0')
+ * // => '09'
+ *
+ * @example
+ * // Align text to the right
+ * padStart('42', 5)
+ * // => '   42'
+ *
+ * @example
+ * // Format IDs
+ * padStart('123', 8, '0')
+ * // => '00000123'
+ */
+declare function padStart(str: string, length: number, chars?: string): string;
+/**
+ * Pads a string on the right (end) to reach the target length.
+ *
+ * @example
+ * // Align text to the left
+ * padEnd('hello', 10)
+ * // => 'hello     '
+ *
+ * @example
+ * // Create fixed-width columns
+ * padEnd('Name', 20) + padEnd('Age', 5)
+ * // => 'Name                Age  '
+ *
+ * @example
+ * // Pad with custom character
+ * padEnd('1', 4, '0')
+ * // => '1000'
+ *
+ * @example
+ * // Format file sizes
+ * padEnd('1.5', 6, '0') + ' MB'
+ * // => '1.5000 MB'
+ */
+declare function padEnd(str: string, length: number, chars?: string): string;
+
+export { camelCase, capitalize, deburr, escape, escapeRegExp, kebabCase, pad, padEnd, padStart, pascalCase, slugify, snakeCase, template, truncate, uncapitalize, unescape, words };