Skip to content

Commit b1f213c

Browse files
vmcruzvmcruz
committed
@sandboxed/diff first release
0 parents  commit b1f213c

36 files changed

+15153
-0
lines changed

‎.github/workflows/create_release.yaml

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Create Release
2+
run-name: Create ${{ inputs.release_type }} release
3+
4+
on:
5+
workflow_dispatch:
6+
inputs:
7+
release_type:
8+
type: choice
9+
description: 'Select the release type'
10+
options:
11+
- patch
12+
- minor
13+
- major
14+
required: true
15+
16+
permissions:
17+
contents: write # Required for committing version bump
18+
19+
jobs:
20+
release:
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v4
26+
with:
27+
fetch-depth: 0
28+
29+
- name: Set up Node.js
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version-file: 'package.json'
33+
34+
- name: Install dependencies
35+
run: npm ci
36+
37+
- name: Verify lint and testing
38+
run: tsc --noEmit && npm run lint && npm run test
39+
40+
- name: Configure github-actions user
41+
run: |
42+
git config --global user.name "github-actions[bot]"
43+
git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
44+
45+
- name: Bump version in package.json
46+
id: version_bump
47+
run: |
48+
VERSION=$(npm version ${{ inputs.release_type }} -m "v%s")
49+
echo "VERSION=$VERSION" >> $GITHUB_ENV
50+
51+
- name: Push version bump and tag
52+
run: |
53+
git push origin main
54+
git push origin $VERSION
55+
56+
- name: Create GitHub Release
57+
uses: softprops/action-gh-release@v2
58+
with:
59+
name: "Release ${{ env.VERSION }}"
60+
draft: true
61+
generate_release_notes: true
62+
tag_name: ${{ env.VERSION }}
63+
env:
64+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/publish.yaml

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Publish to npm
2+
run-name: ${{ github.ref_name }} ${{ inputs.dry_run == true && ' (dry-run)' || '' }}
3+
4+
on:
5+
workflow_dispatch:
6+
inputs:
7+
dry_run:
8+
type: boolean
9+
description: Run as a dry-run (no publish)
10+
default: true
11+
12+
permissions:
13+
id-token: write # Required for --provenancepermissions:
14+
contents: read
15+
packages: write
16+
17+
jobs:
18+
publish:
19+
runs-on: ubuntu-latest
20+
21+
steps:
22+
- run: |
23+
if [[ "${{ github.ref }}" != refs/tags/* ]]; then
24+
echo "This workflow can only be run from a tag."
25+
exit 1
26+
fi
27+
28+
- name: Checkout repository
29+
uses: actions/checkout@v4
30+
31+
- name: Set up Node.js
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version-file: 'package.json'
35+
registry-url: 'https://registry.npmjs.org'
36+
37+
- name: Install dependencies
38+
run: npm ci
39+
40+
- name: Build package
41+
run: npm run build
42+
43+
- name: Extract dist tag from version
44+
id: dist_tag
45+
run: echo "value=$(cat package.json | jq -r '.version | split("-") | .[1] // "latest" | split(".") | .[0]')" >> $GITHUB_OUTPUT
46+
47+
- name: Dry run publish (${{ steps.dist_tag.outputs.value }})
48+
run: npm publish --dry-run --provenance --tag ${{ steps.dist_tag.outputs.value }} --access=public
49+
if: inputs.dry_run == true
50+
51+
- name: Publish to npm
52+
run: npm publish --provenance --tag ${{ steps.dist_tag.outputs.value }} --access=public
53+
if: inputs.dry_run == false
54+
env:
55+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
lerna-debug.log*
8+
.pnpm-debug.log*
9+
10+
# Diagnostic reports (https://nodejs.org/api/report.html)
11+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
12+
13+
# Runtime data
14+
pids
15+
*.pid
16+
*.seed
17+
*.pid.lock
18+
19+
# Directory for instrumented libs generated by jscoverage/JSCover
20+
lib-cov
21+
22+
# Coverage directory used by tools like istanbul
23+
coverage
24+
*.lcov
25+
26+
# nyc test coverage
27+
.nyc_output
28+
29+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
30+
.grunt
31+
32+
# Bower dependency directory (https://bower.io/)
33+
bower_components
34+
35+
# node-waf configuration
36+
.lock-wscript
37+
38+
# Compiled binary addons (https://nodejs.org/api/addons.html)
39+
build/Release
40+
41+
# Dependency directories
42+
node_modules/
43+
jspm_packages/
44+
45+
# Snowpack dependency directory (https://snowpack.dev/)
46+
web_modules/
47+
48+
# TypeScript cache
49+
*.tsbuildinfo
50+
51+
# Optional npm cache directory
52+
.npm
53+
54+
# Optional eslint cache
55+
.eslintcache
56+
57+
# Optional stylelint cache
58+
.stylelintcache
59+
60+
# Microbundle cache
61+
.rpt2_cache/
62+
.rts2_cache_cjs/
63+
.rts2_cache_es/
64+
.rts2_cache_umd/
65+
66+
# Optional REPL history
67+
.node_repl_history
68+
69+
# Output of 'npm pack'
70+
*.tgz
71+
72+
# Yarn Integrity file
73+
.yarn-integrity
74+
75+
# dotenv environment variable files
76+
.env
77+
.env.development.local
78+
.env.test.local
79+
.env.production.local
80+
.env.local
81+
82+
# parcel-bundler cache (https://parceljs.org/)
83+
.cache
84+
.parcel-cache
85+
86+
# Next.js build output
87+
.next
88+
out
89+
90+
# Nuxt.js build / generate output
91+
.nuxt
92+
dist
93+
94+
# Gatsby files
95+
.cache/
96+
# Comment in the public line in if your project uses Gatsby and not Next.js
97+
# https://nextjs.org/blog/next-9-1#public-directory-support
98+
# public
99+
100+
# vuepress build output
101+
.vuepress/dist
102+
103+
# vuepress v2.x temp and cache directory
104+
.temp
105+
.cache
106+
107+
# vitepress build output
108+
**/.vitepress/dist
109+
110+
# vitepress cache directory
111+
**/.vitepress/cache
112+
113+
# Docusaurus cache and generated files
114+
.docusaurus
115+
116+
# Serverless directories
117+
.serverless/
118+
119+
# FuseBox cache
120+
.fusebox/
121+
122+
# DynamoDB Local files
123+
.dynamodb/
124+
125+
# TernJS port file
126+
.tern-port
127+
128+
# Stores VSCode versions used for testing VSCode extensions
129+
.vscode-test
130+
131+
# yarn v2
132+
.yarn/cache
133+
.yarn/unplugged
134+
.yarn/build-state.yml
135+
.yarn/install-state.gz
136+
.pnp.*
137+
138+
lib
139+
140+
.vscode

‎LICENSE

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Copyright (c) 2025 Víctor Cruz
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# @sandboxed/diff
2+
3+
A **zero dependency, high-performance, security-conscious** JavaScript diffing library for comparing complex data structures with ease.
4+
5+
## Features
6+
7+
- ⚡️ **Zero dependencies** – lightweight and no external libraries required
8+
- 📝 Detects **additions, deletions, and modifications**
9+
- 💡 Supports **Primitives, Objects, Arrays, Maps, and Sets**
10+
- 🔄 **Handles circular references** safely
11+
- 🛠️ **Highly configurable** to fit different use cases
12+
- 🚨 **Built with security in mind** to prevent prototype pollution and other risks
13+
- 💻 Works in both **Node.js and browser environments**
14+
15+
## Installation
16+
17+
```
18+
npm install @sandboxed/diff
19+
20+
yarn add @sandboxed/diff
21+
```
22+
23+
### Supports `esm` and `cjs`
24+
25+
Works with both ESM (`import`) and CJS (`require`). Use the syntax that matches your environment:
26+
27+
```javascript
28+
// ESM
29+
import diff, { ChangeType } from '@sandboxed/diff';
30+
31+
// CJS option 1
32+
const diff = require('@sandboxed/diff').default;
33+
const { ChangeType } = require('@sandboxed/diff');
34+
35+
// CJS option 2
36+
const { default: diff, ChangeType } = require('@sandboxed/diff');
37+
```
38+
39+
## Usage
40+
41+
#### `diff(lhs: any, rhs: any, config?: DiffConfig): Diff`
42+
43+
```javascript
44+
import diff, { ChangeType } from '@sandboxed/diff';
45+
46+
const a = { name: "Alice", age: 25 };
47+
const b = { name: "Alice", age: 26, city: "New York" };
48+
49+
const result = diff(a, b);
50+
51+
console.log(result);
52+
console.log(result.toDiffString());
53+
console.log(result.equal); // false
54+
```
55+
56+
**Output**:
57+
58+
```javascript
59+
[
60+
{ type: 'noop', str: '{', depth: 0, path: [] },
61+
{
62+
type: 'noop',
63+
str: '"name": "Alice",',
64+
depth: 1,
65+
path: [ 'name', { deleted: false, value: 'Alice' } ]
66+
},
67+
{
68+
type: 'remove',
69+
str: '"age": 25,',
70+
depth: 1,
71+
path: [ 'age', { deleted: true, value: 25 } ]
72+
},
73+
{
74+
type: 'update',
75+
str: '"age": 26,',
76+
depth: 1,
77+
path: [ 'age', { deleted: false, value: 26 } ]
78+
},
79+
{
80+
type: 'add',
81+
str: '"city": "New York",',
82+
depth: 1,
83+
path: [ 'city', { deleted: false, value: 'New York' } ]
84+
},
85+
{ type: 'noop', str: '}', depth: 0, path: [] }
86+
]
87+
88+
// ---
89+
90+
{
91+
"name": "Alice",
92+
- "age": 25,
93+
! "age": 26,
94+
+ "city": "New York",
95+
}
96+
```
97+
98+
## Config
99+
100+
| option | Description |
101+
|-|-|
102+
|[config.include](/docs/config.md#include-changetype--changetype)| Include only these change types from the diff result. Can be combined with `exclude`. |
103+
|[config.exclude](/docs/config.md#exclude-changetype--changetype)| Excludes the change types from the diff result. Can be combined with `include`. |
104+
|[config.strict](/docs/config.md#strict-boolean)| Performs loose type check if disabled. |
105+
|[config.showUpdatedOnly](/docs/config.md#showupdatedonly-boolean)| `@sandboxed/diff` creates a `ChangeType.REMOVE` entry for every `ChangeType.UPDATE`. This flags prevents this behavior. |
106+
|[config.pathHints](/docs/config.md#pathhints-pathints)| Hashmap of `map` and `set` path hints. These strings will be used in the `path` array to provide a hit about the object's type. |
107+
|[config.redactKeys](/docs/config.md#redactkeys-arraystring)| List of keys that should be redacted from the output. Works with `string` based keys and serialized `Symbol`. |
108+
|[config.maxDepth](/docs/config.md#maxdepth-number)| Max depth that the diffing function can traverse. |
109+
|[config.maxKeys](/docs/config.md#maxkeys-number)| Max keys the diffing function can traverse. |
110+
|[config.timeout](/docs/config.md#timeout-number)| Milliseconds before throwing a timeout error. |
111+
112+
## Utils
113+
114+
| util | Description |
115+
|-|-|
116+
|[toDiffString](/docs/utils.md#diff-string-output)| Generates the diff string representation of the diff result. |
117+
|[equal](/docs/utils.md#equality-detection)| Determines whether the inputs are structurally equal based on the diff result. |
118+
119+
## Motivation
120+
121+
Many diffing libraries are optimized for either structured output or human-readable text, but rarely both. `@sandboxed/diff` is designed to provide a structured diff result along with a utility to generate a string representation, making it easy to use in both programmatic logic and UI rendering.
122+
123+
Trade-off: It may be **slower than other libraries**, but if you prioritize structured diffs with a built-in string representation, `@sandboxed/diff` is a great fit.
124+
125+
## LICENSE
126+
127+
[MIT](LICENSE)

0 commit comments

Comments
 (0)