jell-utils 0.0.17 → 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run semantic-release:*)",
+      "Bash(npm version:*)",
+      "Bash(git add:*)",
+      "Bash(git checkout:*)",
+      "Bash(git merge:*)",
+      "Bash(echo:*)",
+      "Bash(git push:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm run lint)"
+    ],
+    "deny": []
+  }
+}

package/.releaserc.json

@@ -0,0 +1,115 @@
+{
+  "branches": [
+    "main",
+    "master",
+    {
+      "name": "beta",
+      "prerelease": true
+    },
+    {
+      "name": "alpha",
+      "prerelease": true
+    }
+  ],
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          { "type": "feat", "release": "minor" },
+          { "type": "fix", "release": "patch" },
+          { "type": "perf", "release": "patch" },
+          { "type": "revert", "release": "patch" },
+          { "type": "docs", "release": "patch" },
+          { "type": "style", "release": false },
+          { "type": "refactor", "release": "patch" },
+          { "type": "test", "release": false },
+          { "type": "build", "release": false },
+          { "type": "ci", "release": false },
+          { "scope": "no-release", "release": false },
+          { "breaking": true, "release": "major" }
+        ],
+        "parserOpts": {
+          "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"]
+        }
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "conventionalcommits",
+        "presetConfig": {
+          "types": [
+            { "type": "feat", "section": "✨ Features", "hidden": false },
+            { "type": "fix", "section": "🐛 Bug Fixes", "hidden": false },
+            { "type": "perf", "section": "⚡ Performance", "hidden": false },
+            { "type": "revert", "section": "⏪ Reverts", "hidden": false },
+            { "type": "docs", "section": "📝 Documentation", "hidden": false },
+            { "type": "style", "section": "💄 Styles", "hidden": false },
+            {
+              "type": "refactor",
+              "section": "♻️ Refactoring",
+              "hidden": false
+            },
+            { "type": "test", "section": "🧪 Tests", "hidden": false },
+            { "type": "build", "section": "📦 Build", "hidden": false },
+            { "type": "ci", "section": "👷 CI/CD", "hidden": false }
+          ]
+        },
+        "writerOpts": {
+          "commitsSort": ["subject", "scope"]
+        }
+      }
+    ],
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md",
+        "changelogTitle": "# 📋 Changelog\n\nAll notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines."
+      }
+    ],
+    [
+      "@semantic-release/npm",
+      {
+        "npmPublish": true,
+        "tarballDir": "dist"
+      }
+    ],
+    [
+      "@semantic-release/github",
+      {
+        "successComment": "🎉 This ${issue.pull_request ? 'PR is included' : 'issue has been resolved'} in version [${nextRelease.version}](${releases.filter(release => !!release.name)[0].url}) which has been released! 🚀\n\n📦 Install the latest version:\n```bash\nnpm install jell-utils@${nextRelease.version}\n```",
+        "failTitle": "❌ The automated release is failing 🚨",
+        "failComment": "The automated release from the `${branch.name}` branch failed. 😞\n\n📝 Full changelog: ${nextRelease.notes}\n🔍 [Workflow run](${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID})",
+        "labels": ["released"],
+        "releasedLabels": [
+          "released<%= nextRelease.type === 'prerelease' ? `-${nextRelease.prerelease}` : '' %>"
+        ],
+        "addReleases": "bottom",
+        "assets": [
+          {
+            "path": "lib/**/*",
+            "label": "Compiled JavaScript (${nextRelease.version})"
+          },
+          {
+            "path": "dist/*.tgz",
+            "label": "NPM Package (${nextRelease.version})"
+          }
+        ]
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "package.json",
+          "package-lock.json",
+          "CHANGELOG.md",
+          "lib/**/*"
+        ],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ]
+  ]
+}

package/CLAUDE.md

@@ -0,0 +1,139 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a TypeScript utility library (`jell-utils`) containing utility functions primarily focused on:
+- Korean text processing and detection
+- Date/time manipulation and formatting 
+- String transformations (camelCase, snake_case, title case)
+- HTML/text parsing and cleaning
+- Array comparison utilities
+- iOS device detection
+
+The library is designed for both browser and Node.js environments, with compiled output in CommonJS format.
+
+## Development Commands
+
+### Build & Compilation
+```bash
+# Build TypeScript to JavaScript (outputs to lib/ directory)
+yarn build
+# or
+npm run build
+```
+
+### Testing
+```bash
+# Run all tests using Jest
+yarn test
+# or
+npm test
+
+# Test files are in __tests__/ directory
+# Tests are written for TypeScript but run against compiled JS in lib/
+```
+
+### Code Quality
+```bash
+# Lint TypeScript files
+yarn lint
+# or
+npm run lint
+
+# Auto-fix linting issues
+yarn lint:fix
+# or
+npm run lint:fix
+
+# Format code with Prettier
+yarn format
+# or
+npm run format
+```
+
+### Publishing Workflow
+```bash
+# Pre-publish checks (runs test, lint, and lint:fix)
+yarn prepublishOnly
+
+# Version management (includes linting and formatting)
+yarn preversion  # lint check
+yarn version     # format and git add
+yarn postversion # git push with tags
+```
+
+## Architecture & Structure
+
+### Core Module Structure
+- **Source**: `src/index.ts` - Single file containing all utility functions as a default export object
+- **Compiled Output**: `lib/index.js` + `lib/index.d.ts` - ES5 CommonJS with TypeScript declarations
+- **Tests**: `__tests__/korean.test.ts` - Jest tests importing from compiled lib directory
+
+### Key Design Patterns
+- **Single Object Export**: All utilities are methods on a single `util` object
+- **Pure Functions**: All utility functions are stateless and side-effect free (except `clearTag` which uses DOM)
+- **Defensive Programming**: Functions include type checking and fallback values
+- **Browser Compatibility**: Uses DOM APIs for `clearTag` and `navigator` for `isiOS`
+
+### Function Categories
+
+1. **Korean Text Processing**:
+   - `isKorean()` - Detects Korean characters using Unicode ranges
+   
+2. **Date/Time Utilities**:
+   - `getNowDate()` - Current datetime in local timezone
+   - `getKoreanDate()` - Korean date format ("월일" format)
+   - `formatDate()` - yyyy-mm-dd formatting
+   - `calDDay()` - D-day calculator
+   - `parseTime()` - Parse time strings to milliseconds
+
+3. **String Transformations**:
+   - `toCamelCase()` - Convert to camelCase
+   - `toSnakeCase()` - Convert to snake_case  
+   - `toTitleCase()` - Convert to Title Case with space handling
+   - `replaceBetween()` - Replace substring at specific indices
+
+4. **HTML/Text Processing**:
+   - `parseTag()` - Decode HTML entities (&lt; to <)
+   - `toText()` - Convert <br> tags to newlines
+   - `toHtml()` - Convert newlines to <br> tags
+   - `clearTag()` - Remove HTML tags (browser only)
+
+5. **Data Utilities**:
+   - `clone()` - Shallow object cloning
+   - `equalArrays()` - Array comparison
+   - `parseNumber()` - Safe number parsing with defaults
+
+6. **Browser Detection**:
+   - `isiOS()` - Detect iOS devices via user agent
+
+## Development Notes
+
+### Build Process
+- TypeScript compiles to ES5 for broad compatibility
+- Outputs both JavaScript and TypeScript declaration files
+- Uses strict TypeScript configuration with proper module resolution
+
+### Testing Strategy  
+- Tests run against compiled JavaScript in `lib/` directory, not source TypeScript
+- Jest configuration supports both .ts and .js files
+- Tests focus on core functionality rather than edge cases
+
+### Type Safety Considerations
+- Uses `Record<string, unknown>` for generic object types
+- TODO comment indicates need to improve object typing
+- Functions include runtime type checking for safety
+
+### Browser Dependencies
+- `clearTag()` function requires DOM environment (uses `document.createElement`)
+- `isiOS()` function requires browser environment (uses `navigator.userAgent`)
+- Other functions are environment-agnostic
+
+When adding new utilities:
+1. Add to the main util object in `src/index.ts`
+2. Follow existing patterns for type safety and error handling
+3. Add comprehensive JSDoc documentation
+4. Write tests in `__tests__/` directory
+5. Test against compiled output, not source

package/DEPLOYMENT.md

@@ -0,0 +1,351 @@
+# 🚀 Deployment Guide - jell-utils
+
+## 📋 Overview
+
+This project uses a **modern automated CI/CD pipeline** with semantic versioning, conventional commits, and automatic NPM publishing.
+
+### 🎯 Key Features
+
+- ✅ **Automatic versioning** based on conventional commits
+- ✅ **Semantic Release** with changelog generation
+- ✅ **Multi-Node.js version testing** (18.x, 20.x, 21.x)
+- ✅ **Cross-platform testing** (Ubuntu, Windows, macOS)
+- ✅ **Security scanning** and vulnerability checks
+- ✅ **Supply chain security** with provenance attestation
+- ✅ **Automated NPM publishing** to registry
+- ✅ **GitHub releases** with assets and notes
+- ✅ **Slack notifications** (if configured)
+- ✅ **Rollback capabilities** for failed releases
+
+---
+
+## 🔄 Workflow Overview
+
+### 1. 📝 Development Workflow
+
+```mermaid
+graph LR
+    A[Code Changes] --> B[Conventional Commit]
+    B --> C[Push to Feature Branch]
+    C --> D[Create PR to main]
+    D --> E[CI Tests Run]
+    E --> F[Merge to main]
+    F --> G[Auto Release & Deploy]
+```
+
+### 2. 🤖 Automated Pipeline
+
+1. **Quality Gate**: Builds, tests, and lints across multiple environments
+2. **Security Audit**: Vulnerability scanning and dependency analysis
+3. **Release Check**: Semantic analysis of commits for version calculation
+4. **Automated Release**: Version bump, changelog, GitHub release, NPM publish
+5. **Notifications**: Success/failure alerts via Slack and GitHub issues
+
+---
+
+## 🎨 Commit Message Format
+
+This project uses **[Conventional Commits](https://conventionalcommits.org/)** specification.
+
+### Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Supported Types
+
+| Type       | Release        | Description             | Example                                |
+| ---------- | -------------- | ----------------------- | -------------------------------------- |
+| `feat`     | **minor**      | New feature             | `feat: add Korean text detection`      |
+| `fix`      | **patch**      | Bug fix                 | `fix: resolve parseTime radix issue`   |
+| `perf`     | **patch**      | Performance improvement | `perf: optimize toTitleCase algorithm` |
+| `docs`     | **patch**      | Documentation changes   | `docs: update API documentation`       |
+| `refactor` | **patch**      | Code refactoring        | `refactor: simplify isiOS function`    |
+| `test`     | **no release** | Test additions          | `test: add parseNumber edge cases`     |
+| `ci`       | **no release** | CI configuration        | `ci: update GitHub Actions workflow`   |
+| `style`    | **no release** | Code formatting         | `style: fix indentation`               |
+
+### Breaking Changes
+
+Add `BREAKING CHANGE:` in footer or `!` after type for **major** version bump:
+
+```
+feat!: remove deprecated clone function
+
+BREAKING CHANGE: clone function now requires explicit type parameter
+```
+
+### 🛠️ Easy Commit Tool
+
+```bash
+# Interactive commit message builder
+npm run commit
+```
+
+---
+
+## 🚦 Branch Strategy
+
+### Main Branches
+
+- **`main`/`master`**: Production-ready code, auto-deploys to NPM
+- **`beta`**: Beta releases with `-beta` prerelease tag
+- **`alpha`**: Alpha releases with `-alpha` prerelease tag
+
+### Feature Development
+
+1. Create feature branch from `main`
+2. Make changes with conventional commits
+3. Create PR to `main`
+4. Auto-merge after CI passes
+
+---
+
+## ⚙️ Setup Instructions
+
+### 1. 📦 Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. 🎣 Initialize Git Hooks
+
+```bash
+npx husky install
+```
+
+### 3. 🔑 Configure Secrets (Repository Admin)
+
+#### Required GitHub Secrets:
+
+```bash
+# NPM Publishing Token (https://npmjs.com/settings/tokens)
+NPM_TOKEN=npm_xxxxxxxxxxxxxxxx
+
+# Optional: Slack notifications
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+
+# Optional: Code coverage
+CODECOV_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+#### Setting Secrets:
+
+1. Go to repository **Settings** → **Secrets and variables** → **Actions**
+2. Click **New repository secret**
+3. Add each secret above
+
+### 4. 📋 Branch Protection Rules
+
+Configure branch protection for `main`:
+
+1. **Settings** → **Branches** → **Add rule**
+2. Branch name pattern: `main`
+3. Enable:
+   - ✅ Require a pull request before merging
+   - ✅ Require status checks to pass before merging
+   - ✅ Require up-to-date branches before merging
+   - ✅ Include administrators
+
+---
+
+## 🎮 Usage Commands
+
+### Development
+
+```bash
+# Build project
+npm run build
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint and fix code
+npm run lint:fix
+
+# Format code
+npm run format
+
+# Interactive commit (recommended)
+npm run commit
+```
+
+### Release Management
+
+```bash
+# Test semantic release (dry run)
+npm run semantic-release:dry-run
+
+# Manual version bump (emergency only)
+npm run release:patch  # x.x.X
+npm run release:minor  # x.X.0
+npm run release:major  # X.0.0
+```
+
+### CI Commands
+
+```bash
+# Full CI pipeline locally
+npm run ci:install
+npm run ci:build
+npm run ci:test
+npm run ci:lint
+```
+
+---
+
+## 🔧 Configuration Files
+
+### Core Configuration
+
+- **`.releaserc.json`**: Semantic release configuration
+- **`package.json`**: NPM scripts and dependencies
+- **`.github/workflows/`**: GitHub Actions workflows
+
+### Code Quality
+
+- **`.husky/`**: Git hooks for commit validation
+- **`commitlint.config.js`**: Commit message linting
+- **`lint-staged`**: Pre-commit code formatting
+- **`.eslintrc`**: Code linting rules
+
+---
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+#### 1. ❌ Commit Message Rejected
+
+```bash
+Error: Commit message does not follow Conventional Commits format
+```
+
+**Solution**: Use `npm run commit` or follow the format above.
+
+#### 2. ❌ NPM Publish Failed
+
+```bash
+Error: 401 Unauthorized - PUT https://registry.npmjs.org/jell-utils
+```
+
+**Solution**: Check `NPM_TOKEN` in repository secrets.
+
+#### 3. ❌ No Release Created
+
+```bash
+No new version is released
+```
+
+**Solution**: Ensure commits follow conventional format and have appropriate types.
+
+#### 4. ❌ Tests Failing in CI
+
+```bash
+Tests are failing on multiple Node.js versions
+```
+
+**Solution**: Run tests locally on Node.js 18+ and fix compatibility issues.
+
+### 🔄 Manual Recovery
+
+#### Emergency Release
+
+If automated release fails:
+
+```bash
+# 1. Create manual release
+npm version patch  # or minor/major
+git push origin main --tags
+
+# 2. Publish to NPM
+npm publish
+
+# 3. Create GitHub release manually
+```
+
+#### Rollback Release
+
+If release has issues:
+
+```bash
+# 1. Deprecate NPM version
+npm deprecate jell-utils@X.X.X "Version withdrawn due to issues"
+
+# 2. Revert git commits
+git revert <commit-hash>
+git push origin main
+```
+
+---
+
+## 📊 Monitoring & Analytics
+
+### Release Notifications
+
+- ✅ **Slack alerts** for successful/failed releases
+- ✅ **GitHub issues** created for failed deployments
+- ✅ **Email notifications** via GitHub settings
+
+### Package Analytics
+
+- 📈 **NPM download stats**: https://npm-stat.com/charts.html?package=jell-utils
+- 🔍 **Bundle size analysis**: Automated in CI pipeline
+- 📊 **Test coverage reports**: Generated with each release
+
+---
+
+## 🤝 Contributing
+
+### Quick Start for Contributors
+
+1. Fork the repository
+2. Create feature branch: `git checkout -b feat/amazing-feature`
+3. Make changes with conventional commits
+4. Push and create PR
+5. Wait for CI to pass
+6. Merge and automatic release!
+
+### Commit Examples
+
+```bash
+# New feature
+git commit -m "feat: add parseTime millisecond support"
+
+# Bug fix
+git commit -m "fix: handle null values in clone function"
+
+# Documentation
+git commit -m "docs: add deployment guide"
+
+# Breaking change
+git commit -m "feat!: remove deprecated API methods
+
+BREAKING CHANGE: parseOldFormat() has been removed, use parseTime() instead"
+```
+
+---
+
+## 🔗 Useful Links
+
+- 📚 **[Conventional Commits](https://conventionalcommits.org/)**
+- 📖 **[Semantic Release](https://semantic-release.gitbook.io/)**
+- 🚀 **[GitHub Actions](https://docs.github.com/en/actions)**
+- 📦 **[NPM Package](https://www.npmjs.com/package/jell-utils)**
+- 🏠 **[Repository](https://github.com/jellive/jell-utils.js)**
+
+---
+
+## 🆘 Support
+
+- 🐛 **Bug reports**: [Create GitHub Issue](https://github.com/jellive/jell-utils.js/issues/new?template=bug_report.md)
+- 💡 **Feature requests**: [Create GitHub Issue](https://github.com/jellive/jell-utils.js/issues/new?template=feature_request.md)
+- 💬 **Questions**: [GitHub Discussions](https://github.com/jellive/jell-utils.js/discussions)
+
+_Last updated: $(date)_

package/README.md

@@ -10,6 +10,8 @@
 
 This is personal project.
 
+## Change log
+
 ## License
 
 [MIT](LICENSE)