Skip to content

Commit 99e1494

Browse files
r-elr-el
authored
Merge pull request #8 from r-el/feature/prepare-for-npm
feature/prepare for npm
2 parents de64340 + 9ff5556 commit 99e1494

File tree

5 files changed

+277
-6
lines changed

5 files changed

+277
-6
lines changed

‎.github/workflows/ci-cd.yml

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: CI/CD Pipeline
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
pull_request:
7+
branches: [ main, master ]
8+
release:
9+
types: [published]
10+
11+
jobs:
12+
test:
13+
runs-on: ubuntu-latest
14+
strategy:
15+
matrix:
16+
node-version: [16.x, 18.x, 20.x]
17+
18+
steps:
19+
- uses: actions/checkout@v3
20+
21+
- name: Use Node.js ${{ matrix.node-version }}
22+
uses: actions/setup-node@v3
23+
with:
24+
node-version: ${{ matrix.node-version }}
25+
26+
- name: Install dependencies
27+
run: npm install --ignore-scripts
28+
29+
- name: Run tests
30+
run: npm test
31+
32+
- name: Run examples
33+
run: |
34+
node examples/basic-usage.js
35+
node examples/advanced-usage.js
36+
node examples/user-management.js
37+
38+
publish:
39+
needs: test
40+
runs-on: ubuntu-latest
41+
if: github.event_name == 'release' && github.event.action == 'published'
42+
43+
steps:
44+
- uses: actions/checkout@v3
45+
46+
- name: Use Node.js
47+
uses: actions/setup-node@v3
48+
with:
49+
node-version: '18.x'
50+
registry-url: 'https://registry.npmjs.org'
51+
52+
- name: Install dependencies
53+
run: npm install --ignore-scripts
54+
55+
- name: Run tests
56+
run: npm test
57+
58+
- name: Publish to npm
59+
run: npm publish
60+
env:
61+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
62+
63+
lint:
64+
runs-on: ubuntu-latest
65+
66+
steps:
67+
- uses: actions/checkout@v3
68+
69+
- name: Use Node.js
70+
uses: actions/setup-node@v3
71+
with:
72+
node-version: '18.x'
73+
74+
- name: Check package.json
75+
run: |
76+
echo "Checking package.json validity..."
77+
node -e "console.log('package.json is valid JSON')"
78+
79+
- name: Check for required files
80+
run: |
81+
echo "Checking for required files..."
82+
test -f README.md || (echo "README.md not found" && exit 1)
83+
test -f LICENSE || (echo "LICENSE not found" && exit 1)
84+
test -f package.json || (echo "package.json not found" && exit 1)
85+
test -f CHANGELOG.md || (echo "CHANGELOG.md not found" && exit 1)
86+
echo "All required files found"

‎.npmignore

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
# Development files
2-
test/
3-
examples/
42
.git/
53
.gitignore
64

7-
# Test data
5+
# Test data (but keep test files)
86
**/data/
97
test-data/
8+
examples/data/*.json
109

1110
# Development dependencies
1211
node_modules/

‎CHANGELOG.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2025-07-07
9+
10+
### Added
11+
- Initial release of JsonFileCRUD
12+
- Complete CRUD operations (Create, Read, Update, Delete)
13+
- Auto-ID assignment with duplicate prevention
14+
- Configurable ID fields (default: 'id')
15+
- Thread-safe operations with automatic queuing
16+
- Comprehensive error handling and validation
17+
- Zero external dependencies
18+
- Full ESM (ES modules) support
19+
- Comprehensive test suite with 35 tests
20+
- Practical usage examples:
21+
- Basic CRUD operations
22+
- Advanced features with concurrent operations
23+
- User management system example
24+
- Complete API documentation
25+
- Contributing guidelines with improvement ideas
26+
27+
### Features
28+
- **create(item, callback)** - Create new items with auto-ID
29+
- **readAll(callback)** - Read all items from file
30+
- **findById(id, callback)** - Find item by ID
31+
- **findBy(filterFn, callback)** - Find items by custom filter
32+
- **update(id, data, callback)** - Update existing items
33+
- **delete(id, callback)** - Delete items by ID
34+
- **count(callback)** - Get total item count
35+
- **writeAll(items, callback)** - Replace all data
36+
37+
### Performance
38+
- Optimized for small to medium datasets (up to ~10,000 items)
39+
- Sequential operations prevent race conditions
40+
- Automatic file creation on first write
41+
- Memory-efficient data handling
42+
43+
### Documentation
44+
- Complete README with API reference
45+
- Multiple practical examples
46+
- Error handling guide
47+
- Performance considerations
48+
- Contributing guidelines
49+
50+
## [Unreleased]
51+
52+
### Future Improvements
53+
- TypeScript support with .d.ts files
54+
- Promise-based API (async/await)
55+
- Batch operations (createMany, updateMany, deleteMany)
56+
- File locking for multi-process safety
57+
- Enhanced documentation and examples

‎PUBLISHING.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Publishing Guide
2+
3+
This guide explains how to publish new versions of JsonFileCRUD to npm.
4+
5+
## Prerequisites
6+
7+
1. **npm account**: Make sure you have an npm account and are logged in
8+
```bash
9+
npm login
10+
```
11+
12+
2. **npm token**: For GitHub Actions, add your npm token to repository secrets as `NPM_TOKEN`
13+
14+
3. **Repository access**: Make sure you have push access to the GitHub repository
15+
16+
## Publishing Process
17+
18+
### Option 1: Manual Publishing (Recommended for first time)
19+
20+
1. **Update version and changelog:**
21+
```bash
22+
npm version patch # for bug fixes
23+
npm version minor # for new features
24+
npm version major # for breaking changes
25+
```
26+
27+
2. **Verify everything works:**
28+
```bash
29+
npm test
30+
npm run examples
31+
```
32+
33+
3. **Check what will be published:**
34+
```bash
35+
npm pack --dry-run
36+
```
37+
38+
4. **Publish to npm:**
39+
```bash
40+
npm publish
41+
```
42+
43+
### Option 2: Automated Publishing via GitHub Releases
44+
45+
1. **Create a new release on GitHub:**
46+
- Go to the repository on GitHub
47+
- Click "Releases" → "Create a new release"
48+
- Tag version: `v1.0.0` (match package.json version)
49+
- Release title: `Version 1.0.0`
50+
- Description: Copy from CHANGELOG.md
51+
52+
2. **GitHub Actions will automatically:**
53+
- Run all tests
54+
- Run examples
55+
- Publish to npm (if tests pass)
56+
57+
### Option 3: Using npm version command
58+
59+
```bash
60+
# This will:
61+
# 1. Run tests
62+
# 2. Run examples
63+
# 3. Update version in package.json
64+
# 4. Create git tag
65+
# 5. Push to GitHub
66+
npm version patch
67+
```
68+
69+
Then create a GitHub release for the new tag to trigger npm publishing.
70+
71+
## Version Guidelines
72+
73+
- **Patch (1.0.X)**: Bug fixes, documentation updates
74+
- **Minor (1.X.0)**: New features, non-breaking changes
75+
- **Major (X.0.0)**: Breaking changes
76+
77+
## Checklist Before Publishing
78+
79+
- [ ] All tests pass (`npm test`)
80+
- [ ] Examples work (`npm run examples`)
81+
- [ ] CHANGELOG.md updated
82+
- [ ] README.md updated if needed
83+
- [ ] Version number updated in package.json
84+
- [ ] Git changes committed and pushed
85+
86+
## Post-Publishing
87+
88+
1. **Verify the package:**
89+
```bash
90+
npm view json-file-crud
91+
```
92+
93+
2. **Test installation:**
94+
```bash
95+
mkdir test-install
96+
cd test-install
97+
npm init -y
98+
npm install json-file-crud
99+
```
100+
101+
3. **Update documentation** if needed
102+
103+
## Troubleshooting
104+
105+
- **403 Forbidden**: Make sure you're logged in and have permission to publish
106+
- **Version already exists**: Update the version number
107+
- **Tests fail**: Fix issues before publishing
108+
- **Missing files**: Check .npmignore and package.json files array

‎package.json

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"name": "json-file-crud",
33
"version": "1.0.0",
44
"title": "JsonFileCRUD",
5-
"description": "CRUD operations for JSON files",
5+
"description": "A simple, robust, and thread-safe CRUD library for managing JSON objects in files",
66
"main": "./lib/json-file-crud.js",
77
"type": "module",
88
"scripts": {
@@ -14,19 +14,40 @@
1414
"test:update": "node test/test-update.js",
1515
"test:delete": "node test/test-delete.js",
1616
"test:advanced-create": "node test/test-advanced-create.js",
17-
"prepublishOnly": "npm test"
17+
"examples": "node examples/basic-usage.js && node examples/advanced-usage.js && node examples/user-management.js",
18+
"examples:basic": "node examples/basic-usage.js",
19+
"examples:advanced": "node examples/advanced-usage.js",
20+
"examples:user": "node examples/user-management.js",
21+
"version": "npm test && npm run examples && git add CHANGELOG.md",
22+
"preversion": "npm test",
23+
"postversion": "git push && git push --tags",
24+
"prepublishOnly": "npm test && npm run examples"
1825
},
1926
"keywords": [
2027
"crud",
2128
"json",
2229
"file",
2330
"database",
2431
"async",
25-
"callback"
32+
"callback",
33+
"nodejs",
34+
"thread-safe",
35+
"queue",
36+
"auto-id",
37+
"lightweight",
38+
"zero-dependencies"
2639
],
2740
"engines": {
2841
"node": ">=14.0.0"
2942
},
43+
"files": [
44+
"lib/",
45+
"examples/",
46+
"test/",
47+
"README.md",
48+
"CHANGELOG.md",
49+
"LICENSE"
50+
],
3051
"homepage": "https://github.com/r-el/json-file-crud",
3152
"repository": {
3253
"type": "git",

0 commit comments

Comments
 (0)