@haskou/value-objects 1.0.1

package/.editorconfig

@@ -0,0 +1,15 @@
+################################################
+#   ╔═╗╔╦╗╦╔╦╗╔═╗╦═╗┌─┐┌─┐┌┐┌┌─┐┬┌─┐
+#   ║╣  ║║║ ║ ║ ║╠╦╝│  │ ││││├┤ ││ ┬
+#  o╚═╝═╩╝╩ ╩ ╚═╝╩╚═└─┘└─┘┘└┘└  ┴└─┘
+################################################
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 80

package/.eslintignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+tests/

package/.eslintrc.json

@@ -0,0 +1,218 @@
+{
+  "env": {
+    "es2022": true,
+    "node": true,
+    "jest": true
+  },
+  "parser": "@typescript-eslint/parser",
+  "plugins": [
+    "@typescript-eslint",
+    "prettier",
+    "unused-imports",
+    "sonarjs",
+    "perfectionist"
+  ],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended"
+  ],
+  "parserOptions": {
+    "project": ["./tsconfig.json", "./tsconfig.jest.json"],
+    "sourceType": "module"
+  },
+  "rules": {
+    "lines-between-class-members": [
+      "error",
+      "always",
+      {
+        "exceptAfterSingleLine": true
+      }
+    ],
+    "padding-line-between-statements": [
+      "error",
+      {
+        "blankLine": "always",
+        "prev": "import",
+        "next": ["class", "export", "const", "let", "var"]
+      },
+      {
+        "blankLine": "always",
+        "prev": "*",
+        "next": ["return", "if"]
+      }
+    ],
+    "no-extra-boolean-cast": "error",
+    "@typescript-eslint/no-non-null-assertion": "off",
+    "@typescript-eslint/naming-convention": [
+      "error",
+      {
+        "selector": ["variable", "function"],
+        "format": ["camelCase", "PascalCase"],
+        "leadingUnderscore": "allow"
+      },
+      {
+        "selector": "interface",
+        "format": ["PascalCase"],
+        "custom": {
+          "regex": "^[A-Z]",
+          "match": true
+        }
+      }
+    ],
+    "no-unused-vars": "off",
+    "unused-imports/no-unused-imports": "error",
+    "unused-imports/no-unused-vars": [
+      "warn",
+      {
+        "vars": "all",
+        "varsIgnorePattern": "^_",
+        "args": "after-used",
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "@typescript-eslint/no-use-before-define": "warn",
+    "@typescript-eslint/no-inferrable-types": "off",
+    "@typescript-eslint/no-this-alias": "warn",
+    "@typescript-eslint/no-require-imports": "error",
+    "@typescript-eslint/unbound-method": "off",
+    "require-await": "off",
+    "@typescript-eslint/require-await": "error",
+    "@typescript-eslint/no-misused-promises": "off",
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/prefer-for-of": "error",
+    "@typescript-eslint/member-delimiter-style": "off",
+    "@typescript-eslint/no-unsafe-return": "error",
+    "@typescript-eslint/no-unsafe-call": "warn",
+    "@typescript-eslint/no-unsafe-argument": "warn",
+    "max-classes-per-file": ["error", 1],
+    "no-multiple-empty-lines": [
+      1,
+      {
+        "max": 1,
+        "maxEOF": 0
+      }
+    ],
+    "max-len": [
+      "error",
+      {
+        "code": 80,
+        "ignoreStrings": true,
+        "ignoreRegExpLiterals": true,
+        "ignoreTemplateLiterals": true
+      }
+    ],
+    "@typescript-eslint/explicit-member-accessibility": [
+      "error",
+      {
+        "ignoredMethodNames": ["constructor"],
+        "accessibility": "explicit"
+      }
+    ],
+    "new-parens": "error",
+    "no-bitwise": "error",
+    "no-caller": "error",
+    "no-cond-assign": "error",
+    "no-console": "warn",
+    "no-debugger": "error",
+    "no-empty": "error",
+    "no-eval": "error",
+    "no-fallthrough": "off",
+    "no-invalid-this": "off",
+    "no-new-wrappers": "error",
+    "no-throw-literal": "error",
+    "no-trailing-spaces": "error",
+    "no-undef-init": "error",
+    "no-unsafe-finally": "error",
+    "no-unused-expressions": [
+      "error",
+      {
+        "allowShortCircuit": true
+      }
+    ],
+    "no-unused-labels": "error",
+    "object-shorthand": "error",
+    "one-var": ["error", "never"],
+    "radix": "error",
+    "spaced-comment": "error",
+    "use-isnan": "error",
+    "valid-typeof": "off",
+    "complexity": ["error", 8],
+    "@typescript-eslint/member-ordering": [
+      "error",
+      {
+        "default": [
+          "field",
+          "static-field",
+          "private-static-field",
+          "public-static-field",
+          "private-instance-field",
+          "public-instance-field",
+          "private-static-method",
+          "public-static-method",
+          "constructor",
+          "private-method",
+          "public-method"
+        ]
+      }
+    ],
+    "max-params": ["warn", 7],
+    "max-nested-callbacks": ["warn", 2],
+    "max-depth": ["warn", 3],
+    "sonarjs/prefer-single-boolean-return": "error",
+    "sonarjs/no-collapsible-if": "error",
+    "sonarjs/no-duplicated-branches": "error",
+    "sonarjs/no-identical-expressions": "warn",
+    "sonarjs/no-nested-switch": "warn",
+    "perfectionist/sort-objects": [
+      "warn",
+      {
+        "type": "natural",
+        "order": "asc"
+      }
+    ],
+    "perfectionist/sort-imports": [
+      "error",
+      {
+        "type": "natural",
+        "order": "asc"
+      }
+    ],
+    "sonarjs/cognitive-complexity": ["error", 10],
+    "@typescript-eslint/explicit-module-boundary-types": [
+      "error",
+      {
+        "allowedNames": ["toPrimitives"]
+      }
+    ],
+    "no-param-reassign": [
+      "warn",
+      {
+        "props": true
+      }
+    ],
+    "no-restricted-imports": [
+      "error",
+      {
+        "paths": [
+          {
+            "name": "../infrastructure",
+            "message": "Domain layer cannot import infrastructure."
+          }
+        ]
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": ["*.spec.ts"],
+      "rules": {
+        "no-unsafe-argument": "off",
+        "max-statements": "off",
+        "max-lines-per-function": "off",
+        "max-nested-callbacks": ["warn", 4]
+      }
+    }
+  ]
+}

package/.prettierrc.json

@@ -0,0 +1,13 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 80,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "jsxBracketSameLine": false,
+  "semi": true,
+  "arrowParens": "always",
+  "endOfLine": "auto"
+}

package/README.md

@@ -0,0 +1,156 @@
+[![npm version](https://badge.fury.io/js/@haskou%2Fvalue-objects.svg)](https://badge.fury.io/js/@haskou%2Fvalue-objects)
+
+# Value Objects
+
+A TypeScript dependency-less library for creating safe, immutable,
+and validated **Value Objects**. Perfect for applications that require **Domain-Driven Design (DDD)** and **type safety**.
+
+## 🚀 Quick Start
+
+```bash
+npm install @haskou/value-objects
+```
+
+```typescript
+import { Email, PositiveNumber, Color, Hour } from 'value-objects';
+
+// ✅ Automatic validation on construction
+const email = new Email('user@example.com');     // Valid
+const price = new PositiveNumber(29.99);         // Valid
+const color = new Color('#FF0000');              // Valid
+const hour = new Hour('09:30');                  // Valid
+
+// ❌ Immediate errors with invalid values
+const badEmail = new Email('not-an-email');      // Error!
+const badPrice = new PositiveNumber(-5);         // Error!
+```
+
+## 🤔 Why use Value Objects?
+
+**Without Value Objects:**
+```typescript
+function createUser(email: string, age: number): void {
+  // Are they valid? We don't know until runtime
+  if (!email.includes('@')) throw new Error('Invalid email');
+  if (age <= 0) throw new Error('Invalid age');
+  // Creation stuff
+}
+```
+
+**With Value Objects:**
+```typescript
+function createUser(email: Email, age: PositiveNumber): void {
+  // If we get here, values ARE valid
+  // Creation stuff
+}
+```
+
+This prevents defensive programming and if-else validations
+since it implements Null Object pattern (see technical documentation).
+Also value-objects can be modified easily keeping the same logic along
+your application.
+
+## 📦 Available Value Objects
+
+### 🔤 Basic
+- **`StringValueObject`** - Strings with length validation
+- **`NumberValueObject`** - Numbers with math operations
+- **`Integer`** - Whole numbers
+- **`PositiveNumber`** - Positive numbers (> 0)
+
+### ✨ Specialized
+- **`Email`** - Email addresses with automatic validation
+- **`Color`** - Hex colors (#FF0000)
+
+### 🕒 Time
+- **`Hour`** - Time in 24h format (09:30)
+- **`Year`** - Years with leap year calculations
+- **`CalendarDay`** - Calendar days
+- **`Day`** - Days of month (1-31)
+- **`DayOfWeek`** - Days of the week
+- **`Month`** - Months (1-12)
+- **`MonthOfYear`** - Month/year combinations
+- **`Timestamp`** - Timestamps with operations
+- **`TimestampInterval`** - Time intervals
+- **`Duration`** - Duration in milliseconds
+
+### 🌍 Coordinates
+- **`Latitude`** - Latitude (-90 to 90)
+- **`Longitude`** - Longitude (-180 to 180)
+- **`Coordinates`** - Coordinate pairs
+
+### 📝 Other
+- **`Enum`** - Base class for typed enumerations
+
+## 💡 Basic Examples
+
+```typescript
+// Validated strings
+const name = new StringValueObject('John Doe');
+const code = new StringValueObject('ABC', 3); // max 3 characters
+
+// Numbers with operations
+const price = new NumberValueObject(29.99);
+const discount = new NumberValueObject(5.00);
+const total = price.subtract(discount); // 24.99
+
+// Emails
+const email = new Email('user@example.com');
+console.log(email.getDomain()); // 'example.com'
+
+// Colors
+const red = new Color('#FF0000');
+const blue = Color.BLUE; // Predefined color
+
+// Coordinates
+const latitude = new Latitude(40.7128);   // New York
+const longitude = new Longitude(-74.0060);
+const coords = new Coordinates(latitude, longitude);
+
+// Time
+const hour = new Hour('09:30');
+const year = new Year(2024);
+console.log(year.isLeapYear()); // true
+```
+
+## 📚 Technical Documentation
+
+Need more details? Check the complete documentation:
+
+**[📖 TECHNICAL_DOCUMENTATION.md](./TECHNICAL_DOCUMENTATION.md)**
+
+Includes:
+- ✅ Complete API for all Value Objects
+- ✅ Advanced usage examples
+- ✅ Error handling
+- ✅ Design principles (immutability, null safety, etc.)
+- ✅ Composition and extensibility patterns
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a branch: `git checkout -b my-feature`
+3. Make your changes and add tests
+4. Run tests: `npm test`
+5. Submit a pull request
+
+## 📄 License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+**Made with ❤️ and TypeScript**