Merge pull request #21 from sonicbaume/custom-adapters

willwade · web-flow · commit 9c25a404d17a · 2026-02-02T11:56:48.000Z
Add option to provide custom zip adapter
diff --git a/src/core/baseProcessor.ts b/src/core/baseProcessor.ts
@@ -44,6 +44,7 @@ import { AACTree, AACButton, AACSemanticCategory } from './treeStructure';
 import { StringCasing, detectCasing, isNumericOrEmpty } from './stringCasing';
 import { ValidationResult } from '../validation/validationTypes';
 import { BinaryOutput, ProcessorInput } from '../utils/io';
+import type { ZipAdapter } from '../utils/zip';
 
 // Configuration options for processors
 export interface ProcessorOptions {
@@ -71,6 +72,9 @@ export interface ProcessorOptions {
   // Locale for symbol libraries (e.g., 'en-GB', 'en-US')
   // Defaults to 'en-GB' if not specified
   grid3Locale?: string;
+
+  // Optionally provide your own adapter for unzipping the input
+  zipAdapter?: (input: ProcessorInput) => Promise<{ zip: ZipAdapter }>;
 }
 
 // Types for aac-tools-platform compatibility
diff --git a/src/index.browser.ts b/src/index.browser.ts
@@ -38,7 +38,7 @@ export { AstericsGridProcessor } from './processors/astericsGridProcessor';
 // Metrics namespace (pageset analytics)
 export * as Metrics from './metrics';
 
-import { BaseProcessor } from './core/baseProcessor';
+import { BaseProcessor, ProcessorOptions } from './core/baseProcessor';
 import { DotProcessor } from './processors/dotProcessor';
 import { OpmlProcessor } from './processors/opmlProcessor';
 import { ObfProcessor } from './processors/obfProcessor';
@@ -55,30 +55,33 @@ export { configureSqlJs } from './utils/sqlite';
  * @returns The appropriate processor instance
  * @throws Error if the file extension is not supported
  */
-export function getProcessor(filePathOrExtension: string): BaseProcessor {
+export function getProcessor(
+  filePathOrExtension: string,
+  options?: ProcessorOptions
+): BaseProcessor {
   const extension = filePathOrExtension.includes('.')
     ? filePathOrExtension.substring(filePathOrExtension.lastIndexOf('.'))
     : filePathOrExtension;
 
   switch (extension.toLowerCase()) {
     case '.dot':
-      return new DotProcessor();
+      return new DotProcessor(options);
     case '.opml':
-      return new OpmlProcessor();
+      return new OpmlProcessor(options);
     case '.obf':
     case '.obz':
-      return new ObfProcessor();
+      return new ObfProcessor(options);
     case '.gridset':
-      return new GridsetProcessor();
+      return new GridsetProcessor(options);
     case '.spb':
     case '.sps':
-      return new SnapProcessor();
+      return new SnapProcessor(options);
     case '.ce':
-      return new TouchChatProcessor();
+      return new TouchChatProcessor(options);
     case '.plist':
-      return new ApplePanelsProcessor();
+      return new ApplePanelsProcessor(options);
     case '.grd':
-      return new AstericsGridProcessor();
+      return new AstericsGridProcessor(options);
     default:
       throw new Error(`Unsupported file extension: ${extension}`);
   }
diff --git a/src/index.node.ts b/src/index.node.ts
@@ -48,7 +48,7 @@ export * as Translation from './translation';
 // UTILITY FUNCTIONS
 // ===================================================================
 
-import { BaseProcessor } from './core/baseProcessor';
+import { BaseProcessor, ProcessorOptions } from './core/baseProcessor';
 import { DotProcessor } from './processors/dotProcessor';
 import { ExcelProcessor } from './processors/excelProcessor';
 import { OpmlProcessor } from './processors/opmlProcessor';
@@ -70,36 +70,39 @@ import { ObfsetProcessor } from './processors/obfsetProcessor';
  * const processor = getProcessor('/path/to/file.gridset');
  * const tree = processor.loadIntoTree('/path/to/file.gridset');
  */
-export function getProcessor(filePathOrExtension: string): BaseProcessor {
+export function getProcessor(
+  filePathOrExtension: string,
+  options?: ProcessorOptions
+): BaseProcessor {
   // Extract extension from file path
   const extension = filePathOrExtension.includes('.')
     ? filePathOrExtension.substring(filePathOrExtension.lastIndexOf('.'))
     : filePathOrExtension;
 
   switch (extension.toLowerCase()) {
     case '.dot':
-      return new DotProcessor();
+      return new DotProcessor(options);
     case '.xlsx':
-      return new ExcelProcessor();
+      return new ExcelProcessor(options);
     case '.opml':
-      return new OpmlProcessor();
+      return new OpmlProcessor(options);
     case '.obf':
     case '.obz':
-      return new ObfProcessor();
+      return new ObfProcessor(options);
     case '.obfset':
-      return new ObfsetProcessor();
+      return new ObfsetProcessor(options);
     case '.gridset':
     case '.gridsetx':
-      return new GridsetProcessor();
+      return new GridsetProcessor(options);
     case '.spb':
     case '.sps':
-      return new SnapProcessor();
+      return new SnapProcessor(options);
     case '.ce':
-      return new TouchChatProcessor();
+      return new TouchChatProcessor(options);
     case '.plist':
-      return new ApplePanelsProcessor();
+      return new ApplePanelsProcessor(options);
     case '.grd':
-      return new AstericsGridProcessor();
+      return new AstericsGridProcessor(options);
     default:
       throw new Error(`Unsupported file extension: ${extension}`);
   }
diff --git a/src/processors/gridset/helpers.ts b/src/processors/gridset/helpers.ts
@@ -12,7 +12,8 @@ import { execSync } from 'child_process';
 import Database from 'better-sqlite3';
 import { dotNetTicksToDate } from '../../utils/dotnetTicks';
 import { getZipEntriesFromAdapter, resolveGridsetPasswordFromEnv } from './password';
-import { openZipFromInput } from '../../utils/zip';
+import { openZipFromInput, type ZipAdapter } from '../../utils/zip';
+import type { ProcessorInput } from '../../utils/io';
 
 function normalizeZipPath(p: string): string {
   const unified = p.replace(/\\/g, '/');
@@ -62,10 +63,13 @@ export function getAllowedImageEntries(tree: AACTree): Set<string> {
 export async function openImage(
   gridsetBuffer: Uint8Array,
   entryPath: string,
-  password = resolveGridsetPasswordFromEnv()
+  password = resolveGridsetPasswordFromEnv(),
+  zipAdapter?: (input: ProcessorInput) => Promise<{ zip: ZipAdapter }>
 ): Promise<Uint8Array | null> {
   try {
-    const { zip } = await openZipFromInput(gridsetBuffer);
+    const { zip } = zipAdapter
+      ? await zipAdapter(gridsetBuffer)
+      : await openZipFromInput(gridsetBuffer);
     const entries = getZipEntriesFromAdapter(zip, password);
     const want = normalizeZipPath(entryPath);
     const entry = entries.find((e) => normalizeZipPath(e.entryName) === want);
diff --git a/src/processors/gridset/imageDebug.ts b/src/processors/gridset/imageDebug.ts
@@ -5,11 +5,11 @@
  * correctly in Grid3 gridsets.
  */
 
-import { openZipFromInput } from '../../utils/zip';
+import { openZipFromInput, type ZipAdapter } from '../../utils/zip';
 import { getZipEntriesFromAdapter } from './password';
 import { resolveGridsetPasswordFromEnv } from './password';
 import { XMLParser } from 'fast-xml-parser';
-import { decodeText } from '../../utils/io';
+import { decodeText, type ProcessorInput } from '../../utils/io';
 
 export interface ImageIssue {
   gridName: string;
@@ -45,7 +45,8 @@ export interface ImageAuditResult {
  */
 export async function auditGridsetImages(
   gridsetBuffer: Uint8Array,
-  password = resolveGridsetPasswordFromEnv()
+  password = resolveGridsetPasswordFromEnv(),
+  zipAdapter?: (input: ProcessorInput) => Promise<{ zip: ZipAdapter }>
 ): Promise<ImageAuditResult> {
   const issues: ImageIssue[] = [];
   const availableImages = new Set<string>();
@@ -55,7 +56,10 @@ export async function auditGridsetImages(
   let unresolvedImages = 0;
 
   try {
-    const { zip } = await openZipFromInput(gridsetBuffer);
+    const { zip } = zipAdapter
+      ? await zipAdapter(gridsetBuffer)
+      : await openZipFromInput(gridsetBuffer);
+
     const entries = getZipEntriesFromAdapter(zip, password);
     const parser = new XMLParser();
 
diff --git a/src/processors/gridset/wordlistHelpers.ts b/src/processors/gridset/wordlistHelpers.ts
@@ -11,8 +11,8 @@
 
 import { XMLParser, XMLBuilder } from 'fast-xml-parser';
 import { getZipEntriesFromAdapter, resolveGridsetPasswordFromEnv } from './password';
-import { openZipFromInput } from '../../utils/zip';
-import { getNodeRequire, isNodeRuntime } from '../../utils/io';
+import { openZipFromInput, type ZipAdapter } from '../../utils/zip';
+import { getNodeRequire, isNodeRuntime, type ProcessorInput } from '../../utils/io';
 import { decodeText } from '../../utils/io';
 
 /**
@@ -130,13 +130,16 @@ export function wordlistToXml(wordlist: WordList): string {
  */
 export async function extractWordlists(
   gridsetBuffer: Uint8Array,
-  password = resolveGridsetPasswordFromEnv()
+  password = resolveGridsetPasswordFromEnv(),
+  zipAdapter?: (input: ProcessorInput) => Promise<{ zip: ZipAdapter }>
 ): Promise<Map<string, WordList>> {
   const wordlists = new Map<string, WordList>();
   const parser = new XMLParser();
 
   try {
-    const { zip } = await openZipFromInput(gridsetBuffer);
+    const { zip } = zipAdapter
+      ? await zipAdapter(gridsetBuffer)
+      : await openZipFromInput(gridsetBuffer);
     const entries = getZipEntriesFromAdapter(zip, password);
 
     // Process each grid file
diff --git a/src/processors/gridsetProcessor.ts b/src/processors/gridsetProcessor.ts
@@ -450,7 +450,10 @@ class GridsetProcessor extends BaseProcessor {
 
     let zipResult: Awaited<ReturnType<typeof openZipFromInput>>;
     try {
-      zipResult = await openZipFromInput(readBinaryFromInput(filePathOrBuffer));
+      const zipInput = readBinaryFromInput(filePathOrBuffer);
+      zipResult = this.options.zipAdapter
+        ? await this.options.zipAdapter(zipInput)
+        : await openZipFromInput(zipInput);
     } catch (error: any) {
       throw new Error(`Invalid ZIP file format: ${error.message}`);
     }
diff --git a/src/processors/obfProcessor.ts b/src/processors/obfProcessor.ts
@@ -497,7 +497,9 @@ class ObfProcessor extends BaseProcessor {
     }
 
     try {
-      const zipResult = await openZipFromInput(filePathOrBuffer);
+      const zipResult = this.options.zipAdapter
+        ? await this.options.zipAdapter(filePathOrBuffer)
+        : await openZipFromInput(filePathOrBuffer);
       this.zipFile = zipResult.zip;
     } catch (err) {
       console.error('[OBF] Error loading ZIP:', err);
diff --git a/src/processors/touchchatProcessor.ts b/src/processors/touchchatProcessor.ts
@@ -153,7 +153,9 @@ class TouchChatProcessor extends BaseProcessor {
 
       // Step 1: Unzip
       const zipInput = readBinaryFromInput(filePathOrBuffer);
-      const { zip } = await openZipFromInput(zipInput);
+      const { zip } = this.options.zipAdapter
+        ? await this.options.zipAdapter(zipInput)
+        : await openZipFromInput(zipInput);
       const vocabEntry = zip.listFiles().find((name) => name.endsWith('.c4v'));
       if (!vocabEntry) {
         throw new Error('No .c4v vocab DB found in TouchChat export');
diff --git a/src/validation/touchChatValidator.ts b/src/validation/touchChatValidator.ts
@@ -4,8 +4,15 @@
 import * as xml2js from 'xml2js';
 import { BaseValidator } from './baseValidator';
 import { ValidationResult } from './validationTypes';
-import { decodeText, getBasename, getFs, readBinaryFromInput, toUint8Array } from '../utils/io';
-import { openZipFromInput } from '../utils/zip';
+import {
+  decodeText,
+  getBasename,
+  getFs,
+  type ProcessorInput,
+  readBinaryFromInput,
+  toUint8Array,
+} from '../utils/io';
+import { openZipFromInput, type ZipAdapter } from '../utils/zip';
 import { openSqliteDatabase } from '../utils/sqlite';
 
 /**
@@ -31,15 +38,19 @@ export class TouchChatValidator extends BaseValidator {
   /**
    * Check if content is TouchChat format
    */
-  static async identifyFormat(content: any, filename: string): Promise<boolean> {
+  static async identifyFormat(
+    content: any,
+    filename: string,
+    zipAdapter?: (input: ProcessorInput) => Promise<{ zip: ZipAdapter }>
+  ): Promise<boolean> {
     const name = filename.toLowerCase();
     if (name.endsWith('.ce')) {
       return true;
     }
 
     // Try to parse as ZIP and check for .c4v database
     try {
-      const { zip } = await openZipFromInput(content);
+      const { zip } = zipAdapter ? await zipAdapter(content) : await openZipFromInput(content);
       const entries = zip.listFiles();
       if (entries.some((entry) => entry.toLowerCase().endsWith('.c4v'))) {
         return true;
