@stndrds/constants 0.1.0-alpha.14

package/README.md

@@ -0,0 +1,210 @@
+# @stndrds/constants
+
+Standard constants library for And You Create applications.
+
+Provides type-safe constants for:
+- 🌍 Countries (ISO codes, phone codes)
+- 💰 Currencies (codes, symbols, decimals)
+- 🎨 Colors
+- 🔤 Icons
+- 📁 File sizes
+- 📄 MIME types
+
+## Installation
+
+```bash
+pnpm add @stndrds/constants
+```
+
+## Usage
+
+### Countries
+
+```typescript
+import { COUNTRIES, getCountryByIso2, isValidIso2 } from "@stndrds/constants";
+
+// Get country by ISO2 code
+const france = COUNTRIES.FR;
+console.log(france.name);        // "France"
+console.log(france.phoneCode);   // "+33"
+
+// Lookup functions
+const country = getCountryByIso2("FR");
+const isValid = isValidIso2("FR"); // true
+
+// Type-safe ISO codes
+import type { CountryIso2, CountryIso3 } from "@stndrds/constants";
+const code: CountryIso2 = "FR"; // Type-safe
+```
+
+### Currencies
+
+```typescript
+import { CURRENCIES, getCurrency, getCurrencySymbol } from "@stndrds/constants";
+
+// Get currency
+const euro = CURRENCIES.EUR;
+console.log(euro.name);     // "Euro"
+console.log(euro.symbol);   // "€"
+console.log(euro.decimals); // 2
+
+// Helper functions
+const symbol = getCurrencySymbol("EUR"); // "€"
+const currency = getCurrency("USD");
+
+// Type-safe currency codes
+import type { CurrencyCode } from "@stndrds/constants";
+const code: CurrencyCode = "EUR"; // Type-safe
+```
+
+### File Sizes
+
+```typescript
+import { FILE_SIZE, RECOMMENDED_MAX_SIZES, formatBytes, mbToBytes } from "@stndrds/constants";
+
+// Intuitive constants
+const avatarMaxSize = FILE_SIZE.MB_2;      // 2,097,152 bytes
+const documentMaxSize = FILE_SIZE.MB_10;   // 10,485,760 bytes
+const videoMaxSize = FILE_SIZE.MB_500;     // 524,288,000 bytes
+
+// Recommended sizes by use case
+const maxSize = RECOMMENDED_MAX_SIZES.AVATAR;    // 2 MB
+const maxSize = RECOMMENDED_MAX_SIZES.DOCUMENT;  // 10 MB
+const maxSize = RECOMMENDED_MAX_SIZES.VIDEO;     // 500 MB
+
+// Conversion utilities
+const bytes = mbToBytes(5);           // 5,242,880
+const formatted = formatBytes(1048576); // "1 MB"
+
+// Validation
+import { isWithinSizeLimit } from "@stndrds/constants";
+const isValid = isWithinSizeLimit(1048576, FILE_SIZE.MB_5); // true
+```
+
+### MIME Types
+
+```typescript
+import {
+  IMAGE_MIME_TYPES,
+  DOCUMENT_MIME_TYPES,
+  VIDEO_MIME_TYPES,
+  WEB_IMAGES,
+  OFFICE_DOCUMENTS,
+  isImageMimeType,
+  getExtensionFromMimeType,
+} from "@stndrds/constants";
+
+// Individual MIME types
+const jpeg = IMAGE_MIME_TYPES.JPEG;  // "image/jpeg"
+const pdf = DOCUMENT_MIME_TYPES.PDF; // "application/pdf"
+const mp4 = VIDEO_MIME_TYPES.MP4;    // "video/mp4"
+
+// Grouped collections
+const webImages = WEB_IMAGES;           // ["image/jpeg", "image/png", "image/gif", "image/webp"]
+const officeFiles = OFFICE_DOCUMENTS;   // [PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX]
+
+// Type checking
+const isImage = isImageMimeType("image/jpeg"); // true
+const isDoc = isDocumentMimeType("application/pdf"); // true
+
+// Get extension
+const ext = getExtensionFromMimeType("image/jpeg"); // "jpg"
+
+// Type-safe MIME types
+import type { MimeType, ImageMimeType } from "@stndrds/constants";
+const type: MimeType = "image/jpeg"; // Type-safe
+```
+
+### Integration with @stndrds/schema
+
+```typescript
+import { file, location, currency, phone } from "@stndrds/schema";
+import {
+  FILE_SIZE,
+  WEB_IMAGES,
+  DOCUMENT_MIME_TYPES,
+  RECOMMENDED_MAX_SIZES,
+} from "@stndrds/constants";
+
+// File attribute with MIME type validation
+const avatar = file({ id: "avatar", name: "avatar", label: "Avatar" })
+  .maxSize(RECOMMENDED_MAX_SIZES.AVATAR)
+  .allowedTypes(WEB_IMAGES)
+  .build();
+
+// Document upload
+const document = file({ id: "doc", name: "document", label: "Document" })
+  .maxSize(FILE_SIZE.MB_10)
+  .allowedTypes([DOCUMENT_MIME_TYPES.PDF, DOCUMENT_MIME_TYPES.DOCX])
+  .build();
+
+// Location with country restriction
+const address = location({ id: "addr", name: "address", label: "Address" })
+  .granularity("full")
+  .defaultCountry("FRA")
+  .allowedCountries(["FRA", "DEU", "GBR"])
+  .build();
+
+// Currency with restrictions
+const price = currency({ id: "price", name: "price", label: "Price" })
+  .defaultCurrency("EUR")
+  .allowedCurrencies(["EUR", "USD", "GBP"])
+  .build();
+
+// Phone with default country
+const mobile = phone({ id: "phone", name: "phone", label: "Phone" })
+  .defaultCountry("FRA")
+  .build();
+```
+
+## Available Constants
+
+### Countries
+60+ countries with ISO2, ISO3, numeric codes, and phone codes
+
+### Currencies
+50+ currencies with codes, symbols, and decimal precision
+
+### File Sizes
+- Bytes: B_1, B_10, B_100, B_512
+- Kilobytes: KB_1, KB_2, KB_5, KB_10, KB_50, KB_100, KB_500
+- Megabytes: MB_1, MB_2, MB_5, MB_10, MB_20, MB_25, MB_50, MB_100, MB_200, MB_500
+- Gigabytes: GB_1, GB_2, GB_5, GB_10
+
+### MIME Types
+- Images: JPEG, PNG, GIF, WebP, SVG, BMP, TIFF, HEIC, HEIF
+- Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, ODT, TXT, CSV, Markdown
+- Archives: ZIP, RAR, TAR, GZIP, 7Z, BZ2
+- Audio: MP3, WAV, OGG, AAC, FLAC, M4A
+- Video: MP4, WebM, OGG, AVI, MOV, MKV
+- Code: JavaScript, TypeScript, JSON, XML, HTML, CSS, Python, Java
+- Fonts: TTF, OTF, WOFF, WOFF2
+
+## Testing
+
+```bash
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm test:coverage
+```
+
+## Types
+
+All exports are fully typed with TypeScript.
+
+```typescript
+import type {
+  CountryIso2,
+  CountryIso3,
+  CurrencyCode,
+  MimeType,
+  ImageMimeType,
+  DocumentMimeType,
+} from "@stndrds/constants";
+```
+
+## License
+
+MIT