@satoshibits/functional 1.0.2

package/dist/result.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.mjs","sourceRoot":"","sources":["../src/result.mts"],"names":[],"mappings":"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"}

package/dist/types.d.mts

@@ -0,0 +1,439 @@
+/**
+ * @module types
+ * @description Branded types and common type utilities for type-safe domain modeling.
+ * Provides compile-time guarantees for entity IDs and other domain primitives.
+ * Branded types (also known as nominal types) prevent accidental mixing of
+ * semantically different values that have the same underlying type. This module
+ * provides utilities for creating branded types, common domain types, and
+ * advanced TypeScript type utilities.
+ *
+ * @example
+ * ```typescript
+ * import { brand, Brand, UserId, Email, assertNever } from './types.mts';
+ *
+ * // create custom branded types
+ * type OrderId = Brand<string, 'OrderId'>;
+ * const OrderId = brand<string, 'OrderId'>('OrderId');
+ *
+ * // use predefined domain types
+ * const userId = UserId('usr_123');
+ * const email = Email('user@example.com');
+ *
+ * // type-safe function parameters
+ * function getUser(id: UserId): Promise<User> {
+ *   // TypeScript prevents passing wrong ID types
+ *   return userRepository.findById(id);
+ * }
+ *
+ * // exhaustive pattern matching
+ * type Status = 'pending' | 'active' | 'completed';
+ * function handleStatus(status: Status): string {
+ *   switch (status) {
+ *     case 'pending': return 'Waiting...';
+ *     case 'active': return 'In progress';
+ *     case 'completed': return 'Done!';
+ *     default: return assertNever(status);
+ *   }
+ * }
+ * ```
+ *
+ * @category Core
+ * @since 2025-07-03
+ */
+/**
+ * Brand type helper that creates nominal types from structural types.
+ * Prevents accidental mixing of different ID types at compile time.
+ *
+ * @category Core Types
+ */
+export type Brand<T, B> = T & {
+    readonly __brand: B;
+};
+/**
+ * Creates a branded type constructor.
+ *
+ * @category Constructors
+ * @example
+ * const UserId = brand<string, 'UserId'>('UserId');
+ * const userId = UserId('user_123');
+ *
+ * @example
+ * // Type-safe ID creation
+ * const AccountId = brand<string, 'AccountId'>('AccountId');
+ * const CampaignId = brand<string, 'CampaignId'>('CampaignId');
+ *
+ * // This will cause a compile error:
+ * // const wrong: AccountId = campaignId;
+ *
+ * @example
+ * // With validation
+ * const PositiveNumber = brand<number, 'PositiveNumber'>('PositiveNumber',
+ *   (n) => n > 0 ? n : throw new Error('Must be positive')
+ * );
+ */
+export declare const brand: <T, B extends string>(_brandName: B, validate?: (value: T) => T) => (value: T) => Brand<T, B>;
+/**
+ * Extracts the underlying type from a branded type.
+ *
+ * @category Type Utilities
+ * @example
+ * type UserId = Brand<string, 'UserId'>;
+ * type RawId = Unbrand<UserId>; // string
+ */
+export type Unbrand<T> = T extends Brand<infer U, unknown> ? U : T;
+/**
+ * Common ID types for the application domain.
+ * These provide type safety for entity relationships.
+ *
+ * @category Domain Types
+ */
+/**
+ * Account ID type - identifies a customer account.
+ *
+ * @example
+ * const accountId = AccountId('acc_123456');
+ *
+ * @example
+ * // Type-safe function parameters
+ * function getAccount(id: AccountId): Promise<Account> {
+ *   return accountRepository.findById(id);
+ * }
+ *
+ * @example
+ * // Prevents mixing IDs
+ * const userId = UserId('usr_789');
+ * // getAccount(userId); // Compile error!
+ */
+export type AccountId = Brand<string, 'AccountId'>;
+export declare const AccountId: (value: string) => Brand<string, "AccountId">;
+/**
+ * User ID type - identifies a user within an account.
+ *
+ * @example
+ * const userId = UserId('usr_789012');
+ *
+ * @example
+ * // Domain modeling
+ * interface User {
+ *   id: UserId;
+ *   accountId: AccountId;
+ *   email: Email;
+ *   name: string;
+ * }
+ */
+export type UserId = Brand<string, 'UserId'>;
+export declare const UserId: (value: string) => Brand<string, "UserId">;
+/**
+ * Campaign ID type - identifies an email campaign.
+ *
+ * @example
+ * const campaignId = CampaignId('camp_abc123');
+ *
+ * @example
+ * // Repository methods
+ * class CampaignRepository {
+ *   async findById(id: CampaignId): Promise<Campaign | null> {
+ *     // Implementation
+ *   }
+ * }
+ */
+export type CampaignId = Brand<string, 'CampaignId'>;
+export declare const CampaignId: (value: string) => Brand<string, "CampaignId">;
+/**
+ * Profile ID type - identifies a subscriber profile.
+ *
+ * @example
+ * const profileId = ProfileId('prof_def456');
+ */
+export type ProfileId = Brand<string, 'ProfileId'>;
+export declare const ProfileId: (value: string) => Brand<string, "ProfileId">;
+/**
+ * Segment ID type - identifies a subscriber segment.
+ *
+ * @example
+ * const segmentId = SegmentId('seg_ghi789');
+ */
+export type SegmentId = Brand<string, 'SegmentId'>;
+export declare const SegmentId: (value: string) => Brand<string, "SegmentId">;
+/**
+ * Email Template ID type - identifies an email template.
+ *
+ * @example
+ * const templateId = EmailTemplateId('tpl_jkl012');
+ */
+export type EmailTemplateId = Brand<string, 'EmailTemplateId'>;
+export declare const EmailTemplateId: (value: string) => Brand<string, "EmailTemplateId">;
+/**
+ * Engine ID type - identifies an automation engine.
+ *
+ * @example
+ * const engineId = EngineId('eng_mno345');
+ */
+export type EngineId = Brand<string, 'EngineId'>;
+export declare const EngineId: (value: string) => Brand<string, "EngineId">;
+/**
+ * Import ID type - identifies a data import job.
+ *
+ * @example
+ * const importId = ImportId('imp_pqr678');
+ */
+export type ImportId = Brand<string, 'ImportId'>;
+export declare const ImportId: (value: string) => Brand<string, "ImportId">;
+/**
+ * Value object types for domain modeling.
+ * These ensure data integrity at the type level.
+ *
+ * @category Value Objects
+ */
+/**
+ * Email address type with basic validation.
+ *
+ * @example
+ * const email = Email('user@example.com');
+ *
+ * @example
+ * // With validation
+ * try {
+ *   const email = Email('invalid-email');
+ * } catch (e) {
+ *   console.error('Invalid email format');
+ * }
+ *
+ * @example
+ * // Type-safe email handling
+ * function sendEmail(to: Email, subject: string): Promise<void> {
+ *   return emailService.send(to, subject);
+ * }
+ */
+export type Email = Brand<string, 'Email'>;
+export declare const Email: (value: string) => Brand<string, "Email">;
+/**
+ * URL type with validation.
+ *
+ * @example
+ * const website = Url('https://example.com');
+ *
+ * @example
+ * // API endpoints
+ * const apiEndpoint = Url('https://api.example.com/v1/users');
+ *
+ * @example
+ * // Validation
+ * try {
+ *   const invalid = Url('not-a-url');
+ * } catch (e) {
+ *   console.error('Invalid URL');
+ * }
+ */
+export type Url = Brand<string, 'Url'>;
+export declare const Url: (value: string) => Brand<string, "Url">;
+/**
+ * Positive integer type.
+ *
+ * @example
+ * const count = PositiveInt(42);
+ *
+ * @example
+ * // Domain constraints
+ * interface PaginationParams {
+ *   page: PositiveInt;
+ *   limit: PositiveInt;
+ * }
+ *
+ * @example
+ * // Validation
+ * try {
+ *   const invalid = PositiveInt(-5);
+ * } catch (e) {
+ *   console.error('Must be positive');
+ * }
+ */
+export type PositiveInt = Brand<number, 'PositiveInt'>;
+export declare const PositiveInt: (value: number) => Brand<number, "PositiveInt">;
+/**
+ * Percentage type (0-100).
+ *
+ * @example
+ * const discount = Percentage(15);
+ *
+ * @example
+ * // Business rules
+ * interface Campaign {
+ *   openRate: Percentage;
+ *   clickRate: Percentage;
+ *   bounceRate: Percentage;
+ * }
+ */
+export type Percentage = Brand<number, 'Percentage'>;
+export declare const Percentage: (value: number) => Brand<number, "Percentage">;
+/**
+ * ISO date string type.
+ *
+ * @example
+ * const date = ISODateString('2024-01-15T10:30:00Z');
+ *
+ * @example
+ * // API contracts
+ * interface Event {
+ *   id: string;
+ *   timestamp: ISODateString;
+ *   type: string;
+ * }
+ */
+export type ISODateString = Brand<string, 'ISODateString'>;
+export declare const ISODateString: (value: string) => Brand<string, "ISODateString">;
+/**
+ * Non-empty string type.
+ *
+ * @example
+ * const name = NonEmptyString('John Doe');
+ *
+ * @example
+ * // Form validation
+ * interface UserForm {
+ *   firstName: NonEmptyString;
+ *   lastName: NonEmptyString;
+ *   bio?: string;
+ * }
+ */
+export type NonEmptyString = Brand<string, 'NonEmptyString'>;
+export declare const NonEmptyString: (value: string) => Brand<string, "NonEmptyString">;
+/**
+ * Utility type helpers.
+ *
+ * @category Type Utilities
+ */
+/**
+ * Deep readonly type for immutable data structures.
+ *
+ * @example
+ * type Config = DeepReadonly<{
+ *   api: {
+ *     endpoint: string;
+ *     timeout: number;
+ *   };
+ * }>;
+ */
+export type DeepReadonly<T> = {
+    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+/**
+ * Makes specified keys required while keeping others optional.
+ *
+ * @example
+ * type User = {
+ *   id?: string;
+ *   name?: string;
+ *   email?: string;
+ * };
+ *
+ * type SavedUser = RequireKeys<User, 'id'>;
+ * // { id: string; name?: string; email?: string; }
+ */
+export type RequireKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;
+/**
+ * Makes specified keys optional while keeping others required.
+ *
+ * @example
+ * type Config = {
+ *   apiKey: string;
+ *   timeout: number;
+ *   debug: boolean;
+ * };
+ *
+ * type PartialConfig = OptionalKeys<Config, 'timeout' | 'debug'>;
+ * // { apiKey: string; timeout?: number; debug?: boolean; }
+ */
+export type OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Extracts keys of type T that have values of type V.
+ *
+ * @example
+ * type User = {
+ *   id: string;
+ *   name: string;
+ *   age: number;
+ *   isActive: boolean;
+ * };
+ *
+ * type StringKeys = KeysOfType<User, string>; // 'id' | 'name'
+ * type NumberKeys = KeysOfType<User, number>; // 'age'
+ */
+export type KeysOfType<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];
+/**
+ * Nominal type helper for creating distinct types from primitives.
+ * Similar to Brand but more lightweight.
+ *
+ * @example
+ * type Miles = Nominal<number, 'Miles'>;
+ * type Kilometers = Nominal<number, 'Kilometers'>;
+ *
+ * const distance: Miles = 100 as Miles;
+ * // const wrong: Kilometers = distance; // Error!
+ */
+export type Nominal<T, K> = T & {
+    readonly __nominal: K;
+};
+/**
+ * Type guard creator for branded types.
+ *
+ * @category Type Guards
+ * @example
+ * const isUserId = isBrand<string, 'UserId'>('UserId');
+ *
+ * if (isUserId(value)) {
+ *   // TypeScript knows value is UserId
+ * }
+ *
+ * @example
+ * // Array filtering
+ * const userIds = mixedIds.filter(isUserId);
+ */
+export declare const isBrand: <T, B extends string>(brandName: B) => (value: unknown) => value is Brand<T, B>;
+/**
+ * Creates a type-safe enum from an object.
+ *
+ * @category Enum Utilities
+ * @example
+ * const Status = createEnum({
+ *   PENDING: 'pending',
+ *   ACTIVE: 'active',
+ *   COMPLETED: 'completed'
+ * });
+ *
+ * type Status = EnumType<typeof Status>;
+ * // 'pending' | 'active' | 'completed'
+ *
+ * @example
+ * // Usage in interfaces
+ * interface Task {
+ *   id: string;
+ *   status: Status;
+ * }
+ */
+export declare const createEnum: <T extends Record<string, string>>(obj: T) => Readonly<T>;
+export type EnumType<T> = T[keyof T];
+/**
+ * Assertion function for exhaustive checks.
+ *
+ * @category Type Guards
+ * @example
+ * type Status = 'pending' | 'active' | 'completed';
+ *
+ * function handleStatus(status: Status) {
+ *   switch (status) {
+ *     case 'pending':
+ *       return 'Waiting...';
+ *     case 'active':
+ *       return 'In progress';
+ *     case 'completed':
+ *       return 'Done!';
+ *     default:
+ *       return assertNever(status); // Ensures all cases handled
+ *   }
+ * }
+ */
+export declare const assertNever: (value: never) => never;
+//# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../src/types.mts"],"names":[],"mappings":"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"}

package/dist/types.mjs

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * @module types
+ * @description Branded types and common type utilities for type-safe domain modeling.
+ * Provides compile-time guarantees for entity IDs and other domain primitives.
+ * Branded types (also known as nominal types) prevent accidental mixing of
+ * semantically different values that have the same underlying type. This module
+ * provides utilities for creating branded types, common domain types, and
+ * advanced TypeScript type utilities.
+ *
+ * @example
+ * ```typescript
+ * import { brand, Brand, UserId, Email, assertNever } from './types.mts';
+ *
+ * // create custom branded types
+ * type OrderId = Brand<string, 'OrderId'>;
+ * const OrderId = brand<string, 'OrderId'>('OrderId');
+ *
+ * // use predefined domain types
+ * const userId = UserId('usr_123');
+ * const email = Email('user@example.com');
+ *
+ * // type-safe function parameters
+ * function getUser(id: UserId): Promise<User> {
+ *   // TypeScript prevents passing wrong ID types
+ *   return userRepository.findById(id);
+ * }
+ *
+ * // exhaustive pattern matching
+ * type Status = 'pending' | 'active' | 'completed';
+ * function handleStatus(status: Status): string {
+ *   switch (status) {
+ *     case 'pending': return 'Waiting...';
+ *     case 'active': return 'In progress';
+ *     case 'completed': return 'Done!';
+ *     default: return assertNever(status);
+ *   }
+ * }
+ * ```
+ *
+ * @category Core
+ * @since 2025-07-03
+ */
+/**
+ * Creates a branded type constructor.
+ *
+ * @category Constructors
+ * @example
+ * const UserId = brand<string, 'UserId'>('UserId');
+ * const userId = UserId('user_123');
+ *
+ * @example
+ * // Type-safe ID creation
+ * const AccountId = brand<string, 'AccountId'>('AccountId');
+ * const CampaignId = brand<string, 'CampaignId'>('CampaignId');
+ *
+ * // This will cause a compile error:
+ * // const wrong: AccountId = campaignId;
+ *
+ * @example
+ * // With validation
+ * const PositiveNumber = brand<number, 'PositiveNumber'>('PositiveNumber',
+ *   (n) => n > 0 ? n : throw new Error('Must be positive')
+ * );
+ */
+export var brand = function (_brandName, validate) {
+    return function (value) {
+        var validated = validate ? validate(value) : value;
+        return validated;
+    };
+};
+export var AccountId = brand('AccountId');
+export var UserId = brand('UserId');
+export var CampaignId = brand('CampaignId');
+export var ProfileId = brand('ProfileId');
+export var SegmentId = brand('SegmentId');
+export var EmailTemplateId = brand('EmailTemplateId');
+export var EngineId = brand('EngineId');
+export var ImportId = brand('ImportId');
+export var Email = brand('Email', function (value) {
+    var emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(value)) {
+        throw new Error("Invalid email format: ".concat(value));
+    }
+    return value.toLowerCase();
+});
+export var Url = brand('Url', function (value) {
+    try {
+        new URL(value);
+        return value;
+    }
+    catch (_a) {
+        throw new Error("Invalid URL format: ".concat(value));
+    }
+});
+export var PositiveInt = brand('PositiveInt', function (value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error("Value must be a positive integer: ".concat(value));
+    }
+    return value;
+});
+export var Percentage = brand('Percentage', function (value) {
+    if (value < 0 || value > 100) {
+        throw new Error("Percentage must be between 0 and 100: ".concat(value));
+    }
+    return value;
+});
+export var ISODateString = brand('ISODateString', function (value) {
+    var date = new Date(value);
+    if (isNaN(date.getTime())) {
+        throw new Error("Invalid ISO date string: ".concat(value));
+    }
+    return value;
+});
+export var NonEmptyString = brand('NonEmptyString', function (value) {
+    if (value.trim().length === 0) {
+        throw new Error('String cannot be empty');
+    }
+    return value;
+});
+/**
+ * Type guard creator for branded types.
+ *
+ * @category Type Guards
+ * @example
+ * const isUserId = isBrand<string, 'UserId'>('UserId');
+ *
+ * if (isUserId(value)) {
+ *   // TypeScript knows value is UserId
+ * }
+ *
+ * @example
+ * // Array filtering
+ * const userIds = mixedIds.filter(isUserId);
+ */
+export var isBrand = function (brandName) {
+    return function (value) {
+        return typeof value === 'object' &&
+            value !== null &&
+            '__brand' in value &&
+            value.__brand === brandName;
+    };
+};
+/**
+ * Creates a type-safe enum from an object.
+ *
+ * @category Enum Utilities
+ * @example
+ * const Status = createEnum({
+ *   PENDING: 'pending',
+ *   ACTIVE: 'active',
+ *   COMPLETED: 'completed'
+ * });
+ *
+ * type Status = EnumType<typeof Status>;
+ * // 'pending' | 'active' | 'completed'
+ *
+ * @example
+ * // Usage in interfaces
+ * interface Task {
+ *   id: string;
+ *   status: Status;
+ * }
+ */
+export var createEnum = function (obj) {
+    return Object.freeze(obj);
+};
+/**
+ * Assertion function for exhaustive checks.
+ *
+ * @category Type Guards
+ * @example
+ * type Status = 'pending' | 'active' | 'completed';
+ *
+ * function handleStatus(status: Status) {
+ *   switch (status) {
+ *     case 'pending':
+ *       return 'Waiting...';
+ *     case 'active':
+ *       return 'In progress';
+ *     case 'completed':
+ *       return 'Done!';
+ *     default:
+ *       return assertNever(status); // Ensures all cases handled
+ *   }
+ * }
+ */
+export var assertNever = function (value) {
+    throw new Error("Unexpected value: ".concat(JSON.stringify(value)));
+};
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../src/types.mts"],"names":[],"mappings":"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"}