Add Incremental Archive Updates

[KazW]

Hi, I needed this feature in an app I'm building, and I let Claude loose on this. I haven't gotten a chance to test this out yet (damn session limits 😅), but I wanted to submit this to see if you're interested in it.

This could be total garbage, but I'll add an update sometime over the next few days if it works with my app. I realize this is a huge branch, so if you just close it, I'll understand completely.

Cheers!

[KazW]

Well, functionally, this works... Or at least creates archives that work perfectly with zip/unzip on Linux, even with gaps in them.

I'll post another update once I get this integrated with my app. I'll be using this to use zip as a file container for a video editing application I'm building. I wanted to be able to edit all the small assets without it needing to completely rewrite potentially GBs of video on every save, so this was my solution.

Another cool application for a feature like this might be a backup app with incremental backups.

[gildas-lormeau]

Thanks for the PR. I've skimmed through it and can confirm that the code was generated using AI and deserves to be studied closely.
I also feel that this feature could be implemented via inheritance from (or delegation to) ZipWriter, which would be less intrusive (e.g. import of Node.js modules) and allow benefiting from tree shaking when building code.

At first glance, here are a few more specific comments. The SeekableWriter API is a little strange for someone like me who is discovering the code without digging into it. In this case, it only seems to know how to truncate data and it offers a read feature, which somewhat contradicts the name of the interface. There is also a TODO in the PR that leads me to believe that there is probably some refactoring work to be done.

Finally, I have already thought about this kind of feature and imagined implementing a class of type ZipEditor. In this respect, your proposal is interesting because it is not what I had in mind (i.e. extending ZipWriter).

I need to think about this slowly. For now, I'll keep your PR open so I can remember it, and think about this (probably slowly).

PS: Feel free to use my answer as a prompt to see if Claude agrees 😜

[KazW]

Here's the details on the TODO from the report:

Technical Debt

TD-1: Code Duplication in openExisting/prependZip

Location: lib/core/zip-writer.js

Issue: ~66 lines of entry import logic duplicated between openExisting() and prependZip() methods.

Resolution: Extract shared helper function importEntriesFromZipReader() that both methods can use.

Priority: Low - working correctly, refactor when convenient.

TODO added: Commit 964ce5cb

[KazW]

Here's Claude's response (I just got it to read the comment thread):
TLDR; There's some questions it has for you at the bottom.

Code Review Updates Plan

PR: #634 (gildas-lormeau/zip.js)
Reviewer: @gildas-lormeau (project owner)
Date: 2026-01-29

---

Summary of Feedback

Gildas-lormeau provided the following feedback:

1. AI-generated code needs close study - Code quality concerns
2. Prefer inheritance/delegation - Less intrusive than modifying ZipWriter directly
3. Avoid Node.js imports in core - Keep core lib environment-agnostic
4. Tree shaking support - Architecture should allow unused code elimination
5. SeekableWriter naming confusion - Has readAt() and truncate(), not typical writer operations
6. TODO for refactoring - Code duplication between openExisting()/prependZip()
7. Consider ZipEditor class - Separate class rather than extending ZipWriter

---

Proposed Changes

1. Rename SeekableWriter → RandomAccessStream

Rationale: The current name SeekableWriter is misleading because it includes:

• readAt(offset, length) - Reading is not a "writer" operation
• truncate() - More of a file operation than write operation
• seek(offset) - Positioning, not writing

New Name: RandomAccessStream or SeekableStream

• Better reflects bidirectional I/O capability
• Aligns with terminology used in other libraries (Java's RandomAccessFile, etc.)

Files to modify:

• lib/core/io.js - Rename class and subclasses:
  • SeekableWriter → RandomAccessStream
  • Uint8ArraySeekableWriter → Uint8ArrayRandomAccessStream
  • FileHandleWriter → FileHandleRandomAccessStream
  • FileSystemAccessSeekableWriter → FileSystemAccessRandomAccessStream
• lib/core/zip-writer.js - Update references
• index.d.ts - Update type definitions
• Export aliases for backward compatibility

---

2. Extract Shared Entry Import Logic

Issue: ~66 lines duplicated between openExisting() and prependZip()

Solution: Create helper function importEntriesFromReader()

/**
 * Import entries from a ZipReader into this ZipWriter's internal state.
 * Used by both prependZip() and openExisting().
 *
 * @param {ZipWriter} zipWriter - Target ZipWriter instance
 * @param {Entry[]} entries - Entries from ZipReader
 * @param {number} baseOffset - Offset for zip64 calculations
 */
function importEntriesFromReader(zipWriter, entries, baseOffset) {
    zipWriter.filenames = new Set(entries.map(entry => entry.filename));
    zipWriter.files = new Map(entries.map(entry => {
        // ... shared entry import logic
        return [entry.filename, entry];
    }));
}

Files to modify:

• lib/core/zip-writer.js - Extract helper, update both methods

---

3. Move Node.js-Specific Writers to Separate Module

Issue: FileHandleWriter is Node.js-specific but lives in core io.js

Solution: Create lib/node/io-node.js for Node.js-specific implementations

New file structure:

lib/
  core/
    io.js              # Core I/O (browser-compatible)
  node/
    io-node.js         # Node.js-specific (FileHandleWriter, etc.)

Files to create/modify:

• lib/node/io-node.js - New file with FileHandleRandomAccessStream
• lib/core/io.js - Remove FileHandleWriter
• Update exports to support tree shaking

---

4. Consider ZipEditor Architecture (Future)

Gildas mentioned he imagined a ZipEditor class. Two approaches:

Option A: Current Approach (Extend ZipWriter)

// Static factory method on ZipWriter
const zipWriter = await ZipWriter.openExisting(writer);

Option B: Separate ZipEditor Class (Gildas's Vision)

// Dedicated class for editing existing archives
class ZipEditor {
    constructor(randomAccessStream) { ... }
    async open() { ... }
    async add(name, reader, options) { ... }
    async remove(entry) { ... }
    async close() { ... }
}

Recommendation: Keep current approach for now but structure code to allow easy migration:

• Extract entry import logic (Step 2)
• Keep openExisting() as static factory
• Document that this may become ZipEditor in future

---

5. Improve Tree Shaking Support

Current issue: All I/O classes bundled together

Solution: Ensure each writer class can be imported independently:

// Allow selective imports
import { ZipWriter } from "zip.js/core";
import { FileHandleRandomAccessStream } from "zip.js/node";
import { FileSystemAccessRandomAccessStream } from "zip.js/browser";

Files to modify:

• lib/node/io-node.js - Separate Node.js exports
• lib/browser/io-browser.js - Separate browser exports (if needed)
• Update rollup config for multiple entry points

---

Implementation Checklist

Phase 1: Code Quality (Non-Breaking)

• Extract importEntriesFromReader() helper function
• Add comprehensive JSDoc comments to new APIs
• Ensure all edge cases are tested

Phase 2: Naming (Minor Breaking)

• Rename SeekableWriter → RandomAccessStream
• Rename subclasses consistently
• Add deprecation aliases for old names
• Update TypeScript definitions

Phase 3: Module Structure (Minor Breaking)

• Create lib/node/io-node.js
• Move FileHandleWriter to node-specific module
• Update exports and documentation
• Verify tree shaking works

Phase 4: Documentation

• Update README with new class names
• Document migration path from old names
• Add examples for Node.js and browser usage

---

Backward Compatibility

To minimize breaking changes:

1. Export aliases for renamed classes:

// Deprecated aliases for backward compatibility
export { RandomAccessStream as SeekableWriter };
export { FileHandleRandomAccessStream as FileHandleWriter };

2. Deprecation warnings (optional):

class SeekableWriter extends RandomAccessStream {
    constructor(...args) {
        console.warn("SeekableWriter is deprecated, use RandomAccessStream");
        super(...args);
    }
}

---

Priority

1. High: Extract shared logic (Step 2) - Addresses TODO, improves maintainability
2. Medium: Rename classes (Step 1) - Improves API clarity
3. Low: Module restructuring (Step 3) - Nice to have for tree shaking
4. Defer: ZipEditor class (Step 4) - Wait for Gildas's input on preferred approach

---

Questions for Maintainer

Before implementing major changes, clarify with @gildas-lormeau:

1. Naming preference: RandomAccessStream vs SeekableStream vs other?
2. Module structure: Preference for separate node/browser entry points?
3. ZipEditor: Should we proceed with current approach or wait for ZipEditor design?
4. Breaking changes: Acceptable in next minor/major release?