gptrans 2.1.8 → 2.2.0

package/README.md

@@ -45,7 +45,9 @@ Here's a simple example to get you started:
 ```javascript
 import GPTrans from 'gptrans';
 
+const dbPath = new URL('./db', import.meta.url).pathname;
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en-US',
   target: 'es-AR',
   model: 'sonnet45'
@@ -74,6 +76,7 @@ When creating a new instance of GPTrans, you can customize:
 
 | Option | Description | Default |
 |--------|-------------|---------|
+| `path` | Absolute directory path for the DeepBase translation cache | Required |
 | `from` | Source language locale (BCP 47) | `en-US` |
 | `target` | Target language locale (BCP 47) | `es` |
 | `model` | Translation model key or array of models for fallback | `sonnet45` `gpt41` |
@@ -96,7 +99,7 @@ For simplified or universal language codes, you can omit the region specificatio
 ## 🔍 How It Works
 
 1. **First-Time Translation Behavior:** On the first request, Gptrans will return the original text while processing the translation in the background. This ensures your application remains responsive without waiting for API calls.
-2. **Translation Caching:** Once processed, translations are stored in `db/gptrans_<tag>.json`. Subsequent requests for the same text will be served instantly from the cache.
+2. **Translation Caching:** Once processed, translations are stored as `gptrans_<tag>.json` under the required absolute `path`. Subsequent requests for the same text will be served instantly from the cache.
 3. **Smart Batch Processing:** Automatically groups translation requests to optimize API usage and provide better context.
 4. **Dynamic Model Integration:** Easily plug in multiple AI translation providers with the ModelMix library.
 5. **Customizable Prompts:** Load and modify translation prompts (see the `prompt/translate.md` file) to fine-tune the translation output.
@@ -132,6 +135,7 @@ The `instruction` option lets you guide the AI translator's style, tone, or beha
 
 ```javascript
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en',
   target: 'es-AR',
   instruction: 'Use natural and colloquial tone'
@@ -168,7 +172,7 @@ Include translations from other languages as context to improve accuracy and con
 
 ```javascript
 // Use English and Portuguese translations as reference
-const gptrans = new GPTrans({ from: 'es', target: 'fr' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'fr' });
 await gptrans.preload({ 
   references: ['en', 'pt'] 
 });
@@ -182,7 +186,7 @@ Translate from an intermediate language instead of the original:
 
 ```javascript
 // Original is Spanish, but translate FROM English TO Portuguese
-const gptrans = new GPTrans({ from: 'es', target: 'pt' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'pt' });
 await gptrans.preload({ 
   baseLanguage: 'en' 
 });
@@ -199,7 +203,7 @@ You can use both options together:
 
 ```javascript
 // Translate from English to German, showing Spanish and Portuguese as reference
-const gptrans = new GPTrans({ from: 'es', target: 'de' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'de' });
 await gptrans.preload({ 
   baseLanguage: 'en',
   references: ['es', 'pt'] 
@@ -215,7 +219,7 @@ await gptrans.preload({
 // English: "The student is very good" (neutral)
 
 // Solution: Translate to Portuguese using English as base
-const ptTranslator = new GPTrans({ from: 'es', target: 'pt' });
+const ptTranslator = new GPTrans({ path: dbPath, from: 'es', target: 'pt' });
 await ptTranslator.preload({ 
   baseLanguage: 'en',     // Use neutral English version
   references: ['es']       // Show original Spanish for context
@@ -236,6 +240,7 @@ GPTrans supports a fallback mechanism for translation models. Instead of providi
 
 ```javascript
 const translator = new GPTrans({
+  path: dbPath,
   model: ['claude46', 'gpt54'],
   // ... other options
 });
@@ -251,7 +256,7 @@ When using multiple models:
 The `refine()` method lets you improve existing translations by running them through the AI again with a specific instruction. It processes translations in batches (same as the translation flow) and only updates entries that genuinely benefit from the refinement.
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
 
 // After translations already exist...
 // Refine with a single instruction
@@ -306,4 +311,3 @@ Contributions are welcome! Please open an issue or submit a pull request on GitH
 GPTrans is released under the MIT License.
 
 Happy translating! 🌍✨
-

package/demo/case_1.js

@@ -1,6 +1,7 @@
 import GPTrans from '../index.js';
 
-const gptrans = new GPTrans({ model: 'sonnet45' });
+const dbPath = new URL('../db', import.meta.url).pathname;
+const gptrans = new GPTrans({ path: dbPath, model: 'sonnet45' });
 
 console.log(gptrans.t('Hello, {name}!', { name: 'Anya' }));
 
@@ -14,6 +15,7 @@ console.log(gptrans.t('Card'));
 
 // Case 2: Translate from Spanish Spain to Spanish Argentina
 const es2ar = new GPTrans({
+    path: dbPath,
     from: 'es-ES',
     target: 'es-AR',
     model: 'sonnet46'
@@ -25,10 +27,10 @@ console.log(es2ar.setContext().t('Tienes fuego?'));
 
 // Case 3
 const ar2es = new GPTrans({
+    path: dbPath,
     from: 'es-AR',
     target: 'es-ES',
     model: 'gpt41'
 });
 
 console.log(ar2es.t('¿Tenés fuego?'));
-

package/demo/case_2.js

@@ -1,7 +1,10 @@
 import GPTrans from '../index.js';
 
+const dbPath = new URL('../db', import.meta.url).pathname;
+
 try {
     const gptrans = new GPTrans({
+        path: dbPath,
         target: 'it',
     });
 
@@ -17,4 +20,4 @@ try {
     console.log(gptrans.t('Card'));
 } catch (e) {
     console.error(e);
-}
+}

package/demo/case_3.js

@@ -1,7 +1,10 @@
 import GPTrans from '../index.js';
 
+const dbPath = new URL('../db', import.meta.url).pathname;
+
 try {
     const gptrans = new GPTrans({
+        path: dbPath,
         target: 'ar',
         from: 'es',
     });
@@ -9,4 +12,4 @@ try {
     console.log(gptrans.t('Cargando...'));
 } catch (e) {
     console.error(e);
-}
+}

package/demo/case_4.js

@@ -5,9 +5,11 @@ import { promises as fs } from 'fs';
 
 // Get current file directory
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const dbPath = new URL('../db', import.meta.url).pathname;
 
 // Initialize translator
 const model = new GPTrans({
+    path: dbPath,
     model: ['sonnet46', 'gpt54'],
     from: 'es',  // Assuming the source file is in Spanish
     target: 'en',
@@ -24,4 +26,3 @@ const content = await fs.readFile(filePath, 'utf-8');
 const translatedContent = model.t(content);
 console.log(translatedContent);
 
-

package/demo/case_language_info.js

@@ -1,8 +1,11 @@
 import GPTrans from '../index.js';
 
+const dbPath = new URL('../db', import.meta.url).pathname;
+
 // Ejemplo: Cómo obtener la información completa del idioma
 
 const gptrans = new GPTrans({
+    path: dbPath,
     from: 'es',
     target: 'en',
 });
@@ -25,6 +28,7 @@ console.log('  Gentilicio:', gptrans.replaceFrom.FROM_DENONYM);        // 'Spani
 console.log('\n📌 Ejemplo con variantes regionales:');
 
 const gptrans2 = new GPTrans({
+    path: dbPath,
     from: 'en-GB',
     target: 'pt-BR',
 });

package/demo/case_parallelism.js

@@ -5,6 +5,7 @@ import { dirname, join } from 'path';
 // Cargar .env desde la carpeta demo
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const dbPath = new URL('../db', import.meta.url).pathname;
 try {
     process.loadEnvFile(join(__dirname, '.env'));
 } catch {
@@ -43,6 +44,7 @@ async function testParallelTranslations() {
         texts.map(async (text, index) => {
             // Todas las instancias comparten el MISMO NOMBRE
             const gptrans = new GPTrans({ 
+                path: dbPath,
                 from: sourceLang, 
                 target: targetLang,
                 model: 'sonnet45',

package/demo/case_references.js

@@ -5,6 +5,7 @@ import { dirname, join } from 'path';
 // Load .env from demo folder
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const dbPath = new URL('../db', import.meta.url).pathname;
 try {
     process.loadEnvFile(join(__dirname, '.env'));
 } catch {
@@ -19,6 +20,7 @@ async function testReferences() {
     
     // First, create translations in English and Portuguese
     const enTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'en',
         model: 'sonnet45',
@@ -27,6 +29,7 @@ async function testReferences() {
     });
     
     const ptTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'pt',
         model: 'sonnet45',
@@ -63,6 +66,7 @@ async function testReferences() {
     
     // Now translate to French using English as reference
     const frTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'fr',
         model: 'sonnet45',
@@ -86,6 +90,7 @@ async function testReferences() {
     
     // Translate from English to Italian (using English as base instead of Spanish)
     const itTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'it',
         model: 'sonnet45',
@@ -110,6 +115,7 @@ async function testReferences() {
     
     // Translate to German with multiple references
     const deTranslator = new GPTrans({ 
+        path: dbPath,
         from: 'es', 
         target: 'de',
         model: 'sonnet45',

package/demo/case_refine.js

@@ -1,11 +1,14 @@
 import GPTrans from '../index.js';
 
+const dbPath = new URL('../db', import.meta.url).pathname;
+
 console.log('🚀 Testing GPTrans Refine\n');
 console.log('='.repeat(70));
 
 async function testRefine() {
     // Step 1: Create initial translations
     const gptrans = new GPTrans({
+        path: dbPath,
         from: 'en-US',
         target: 'es-AR',
         model: 'sonnet45',

package/demo/example-image-translation.js

@@ -11,6 +11,7 @@ async function main() {
     try {
         // Initialize GPTrans with Spanish as target
         const gptrans = new GPTrans({
+            path: path.join(__dirname, 'db'),
             from: 'en-US',
             target: 'es'
         });
@@ -81,4 +82,3 @@ async function main() {
 }
 
 main();
-

package/index.js

@@ -1,10 +1,11 @@
 import DeepBase from 'deepbase';
+import { JsonDriver } from 'deepbase-json';
 import stringHash from 'string-hash';
 import { ModelMix } from 'modelmix';
 import { isoAssoc, isLanguageAvailable } from './isoAssoc.js';
 import { GeminiGenerator } from 'genmix';
 import fs from 'fs';
-import path from 'path';
+import pathModule from 'path';
 
 class GPTrans {
     static #mmixInstances = new Map();
@@ -62,7 +63,11 @@ class GPTrans {
         return isLanguageAvailable(langCode);
     }
 
-    constructor({ from = 'en-US', target = 'es', model = 'sonnet46', batchThreshold = 1500, debounceTimeout = 500, promptFile = null, name = '', context = '', instruction = '', freeze = false, debug = false } = {}) {
+    constructor({ from = 'en-US', target = 'es', model = 'sonnet46', batchThreshold = 1500, debounceTimeout = 500, promptFile = null, name = '', context = '', instruction = '', freeze = false, debug = false, path: dbPath } = {}) {
+
+        if (typeof dbPath !== 'string' || !pathModule.isAbsolute(dbPath)) {
+            throw new TypeError('GPTrans requires an absolute "path" option.');
+        }
 
         target = this.normalizeBCP47(target);
         from = this.normalizeBCP47(from);
@@ -73,12 +78,12 @@ class GPTrans {
             /* optional .env missing or unreadable */
         }
 
-        const path = new URL('../../db', import.meta.url).pathname;
         const namePrefix = name ? '_' + name : '';
-        this.dbPath = path;
+        this.dbPath = dbPath;
         this.instanceName = name;
-        this.dbTarget = new DeepBase({ name: 'gptrans' + namePrefix + '_' + target, path });
-        this.dbFrom = new DeepBase({ name: 'gptrans' + namePrefix + '_from_' + from, path });
+        this.dbTarget = this._createDatabase('gptrans' + namePrefix + '_' + target);
+        this.dbFrom = this._createDatabase('gptrans' + namePrefix + '_from_' + from);
+        this.pendingSourceWrites = Promise.resolve();
 
         try {
             this.replaceTarget = isoAssoc(target, 'TARGET_');
@@ -116,6 +121,17 @@ class GPTrans {
         return iso.toLowerCase();
     }
 
+    _createDatabase(name) {
+        return new DeepBase(new JsonDriver({ name, path: this.dbPath }));
+    }
+
+    _saveSourceText(context, contextHash, key, text) {
+        this.pendingSourceWrites = this.pendingSourceWrites.then(async () => {
+            await this.dbFrom.set(context, key, text);
+            await this.dbFrom.set('_context', contextHash, context);
+        });
+    }
+
     setContext(context = '') {
         if (this.context !== context && this.pendingTranslations.size > 0) {
             clearTimeout(this.debounceTimer);
@@ -143,9 +159,10 @@ class GPTrans {
         // If this key was enqueued via t(), avoid duplicate work in a later batch.
         this._dequeuePendingTranslation(key);
 
+        await this.pendingSourceWrites;
         const translatedText = await this._translate(text, [[key, text]], {}, this.preloadBaseLanguage);
         const immediateTranslation = translatedText.trim();
-        this.dbTarget.set(contextHash, key, immediateTranslation);
+        await this.dbTarget.set(contextHash, key, immediateTranslation);
 
         return this._applyParams(immediateTranslation, params);
     }
@@ -171,11 +188,10 @@ class GPTrans {
         }
 
         const contextHash = this._hash(this.context);
-        const translation = this.dbTarget.get(contextHash, key);
+        const translation = this.dbTarget.getSync(contextHash, key);
 
-        if (!this.freeze && !this.dbFrom.get(this.context, key)) {
-            this.dbFrom.set(this.context, key, text);
-            this.dbFrom.set('_context', contextHash, this.context);
+        if (!this.freeze && !this.dbFrom.getSync(this.context, key)) {
+            this._saveSourceText(this.context, contextHash, key, text);
         }
 
         if (translation) {
@@ -233,16 +249,17 @@ class GPTrans {
     async _processBatch(context) {
 
         const batch = Array.from(this.pendingTranslations.entries());
+        const batchCharCount = this.pendingCharCount;
 
         // Clear pending translations and character count before awaiting translation
         this.pendingTranslations.clear();
+        this.pendingCharCount = 0;
+        await this.pendingSourceWrites;
 
-        this.modelConfig.options.max_tokens = this.pendingCharCount + 1000;
-        const minTime = Math.floor((60000 / (8000 / this.pendingCharCount)) * 1.4);
+        this.modelConfig.options.max_tokens = batchCharCount + 1000;
+        const minTime = Math.floor((60000 / (8000 / batchCharCount)) * 1.4);
         GPTrans.mmix(this.modelKey, this.modelMixOptions).limiter.updateSettings({ minTime });
 
-        this.pendingCharCount = 0;
-
         // Load references for each text in the batch if preloadReferences is set
         const batchReferences = {};
         if (this.preloadReferences && this.preloadReferences.length > 0) {
@@ -280,7 +297,7 @@ class GPTrans {
                 const minLength = Math.min(translatedTexts.length, batch.length);
                 for (let i = 0; i < minLength; i++) {
                     if (translatedTexts[i] && translatedTexts[i].trim()) {
-                        this.dbTarget.set(contextHash, batch[i][0], translatedTexts[i].trim());
+                        await this.dbTarget.set(contextHash, batch[i][0], translatedTexts[i].trim());
                     }
                 }
                 return;
@@ -295,15 +312,15 @@ class GPTrans {
                 return;
             }
 
-            batch.forEach(([key], index) => {
+            for (const [index, [key]] of batch.entries()) {
                 if (!trimmed[index]) {
                     console.error(`❌ No translation found for ${key} at index ${index}`);
                     console.error(`   Original text: ${batch[index][1]}`);
-                    return;
+                    continue;
                 }
 
-                this.dbTarget.set(contextHash, key, trimmed[index]);
-            });
+                await this.dbTarget.set(contextHash, key, trimmed[index]);
+            }
 
         } catch (e) {
             console.error('❌ Error in _processBatch:', e.message);
@@ -411,12 +428,9 @@ class GPTrans {
 
         for (const lang of referenceLangs) {
             const namePrefix = this.instanceName ? '_' + this.instanceName : '';
-            const dbRef = new DeepBase({
-                name: `gptrans${namePrefix}_${lang}`,
-                path: this.dbPath
-            });
+            const dbRef = this._createDatabase(`gptrans${namePrefix}_${lang}`);
 
-            const translation = dbRef.get(contextHash, key);
+            const translation = dbRef.getSync(contextHash, key);
             if (translation) {
                 references[lang] = translation;
             }
@@ -427,6 +441,8 @@ class GPTrans {
 
     async preload({ references = [], baseLanguage = null } = {}) {
 
+        await this.pendingSourceWrites;
+
         if (!this.context && this.replaceFrom.FROM_ISO === this.replaceTarget.TARGET_ISO) {
             return this;
         }
@@ -454,7 +470,7 @@ class GPTrans {
         // Track which keys need translation
         const keysNeedingTranslation = [];
 
-        for (const [context, pairs] of this.dbFrom.entries()) {
+        for (const [context, pairs] of Object.entries(this.dbFrom.getSync() ?? {})) {
             // Skip the _context metadata
             if (context === '_context') continue;
 
@@ -463,7 +479,7 @@ class GPTrans {
 
             for (const [key, text] of Object.entries(pairs)) {
                 // Check if translation already exists
-                if (!this.dbTarget.get(contextHash, key)) {
+                if (!this.dbTarget.getSync(contextHash, key)) {
                     keysNeedingTranslation.push({ context, contextHash, key });
                     // Only call get() if translation doesn't exist
                     this.get(key, text);
@@ -488,7 +504,7 @@ class GPTrans {
                 // Check if all needed translations are now complete
                 let allTranslated = true;
                 for (const { contextHash, key } of keysNeedingTranslation) {
-                    if (!this.dbTarget.get(contextHash, key)) {
+                    if (!this.dbTarget.getSync(contextHash, key)) {
                         allTranslated = false;
                         break;
                     }
@@ -514,12 +530,14 @@ class GPTrans {
     }
 
     async purge() {
+        await this.pendingSourceWrites;
+
         // Iterate through dbTarget and remove keys that don't exist in dbFrom
-        for (const [contextHash, pairs] of this.dbTarget.entries()) {
+        for (const [contextHash, pairs] of Object.entries(this.dbTarget.getSync() ?? {})) {
             for (const key of Object.keys(pairs)) {
 
-                const context = this.dbFrom.get('_context', contextHash);
-                if (!this.dbFrom.get(context, key)) {
+                const context = this.dbFrom.getSync('_context', contextHash);
+                if (!this.dbFrom.getSync(context, key)) {
                     console.log(contextHash, key);
                     await this.dbTarget.del(contextHash, key);
                 }
@@ -546,7 +564,7 @@ class GPTrans {
         let currentBatch = [];
         let currentCharCount = 0;
 
-        for (const [contextHash, pairs] of this.dbTarget.entries()) {
+        for (const [contextHash, pairs] of Object.entries(this.dbTarget.getSync() ?? {})) {
             for (const [key, translation] of Object.entries(pairs)) {
                 const entryCharCount = translation.length;
 
@@ -607,20 +625,20 @@ class GPTrans {
                 const minLength = Math.min(refinedTexts.length, entries.length);
                 for (let i = 0; i < minLength; i++) {
                     if (refinedTexts[i] && refinedTexts[i].trim()) {
-                        this.dbTarget.set(entries[i].contextHash, entries[i].key, refinedTexts[i].trim());
+                        await this.dbTarget.set(entries[i].contextHash, entries[i].key, refinedTexts[i].trim());
                     }
                 }
                 return;
             }
 
-            entries.forEach((entry, index) => {
+            for (const [index, entry] of entries.entries()) {
                 const refinedText = refinedTexts[index]?.trim();
                 if (!refinedText) {
                     console.error(`❌ No refined text for ${entry.key} at index ${index}`);
-                    return;
+                    continue;
                 }
-                this.dbTarget.set(entry.contextHash, entry.key, refinedText);
-            });
+                await this.dbTarget.set(entry.contextHash, entry.key, refinedText);
+            }
 
         } catch (e) {
             console.error('❌ Error in _processRefineBatch:', e.message);
@@ -668,13 +686,13 @@ class GPTrans {
         } = options;
 
         // Parse image filename and extension
-        const parsedPath = path.parse(imagePath);
+        const parsedPath = pathModule.parse(imagePath);
         const filename = parsedPath.base;
         const targetLang = this.replaceTarget.TARGET_ISO || 'en';
 
         // Check if image is already in a language folder
-        const dirName = path.basename(path.dirname(imagePath));
-        const parentDir = path.dirname(path.dirname(imagePath));
+        const dirName = pathModule.basename(pathModule.dirname(imagePath));
+        const parentDir = pathModule.dirname(pathModule.dirname(imagePath));
 
         // If the image is in a language folder (e.g., en/image.jpg)
         // create the target at the same level (e.g., es/image.jpg)
@@ -683,12 +701,12 @@ class GPTrans {
 
         if (this._isLanguageFolder(dirName)) {
             // Image is in a language folder: create sibling folder
-            targetDir = path.join(parentDir, targetLang);
-            targetPath = path.join(targetDir, filename);
+            targetDir = pathModule.join(parentDir, targetLang);
+            targetPath = pathModule.join(targetDir, filename);
         } else {
             // Image is not in a language folder: create subfolder
-            targetDir = path.join(path.dirname(imagePath), targetLang);
-            targetPath = path.join(targetDir, filename);
+            targetDir = pathModule.join(pathModule.dirname(imagePath), targetLang);
+            targetPath = pathModule.join(targetDir, filename);
         }
 
         // Check if translated image already exists
@@ -736,7 +754,7 @@ class GPTrans {
             }
 
             // Save translated image - preserve original file format
-            const filename = path.basename(targetPath, path.extname(targetPath));
+            const filename = pathModule.basename(targetPath, pathModule.extname(targetPath));
             const formatOptions = generator.getReferenceMetadata();
 
             // Apply default quality settings for JPEG images
@@ -755,4 +773,4 @@ class GPTrans {
     }
 }
 
-export default GPTrans;
+export default GPTrans;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gptrans",
   "type": "module",
-  "version": "2.1.8",
+  "version": "2.2.0",
   "description": "🚆 GPTrans - The smarter AI-powered way to translate.",
   "keywords": [
     "translate",
@@ -35,9 +35,10 @@
     "node": ">=20.6.0"
   },
   "dependencies": {
-    "deepbase": "^1.5.6",
-    "genmix": "^1.2.4",
-    "modelmix": "^4.5.6",
+    "deepbase": "^3.9.0",
+    "deepbase-json": "3.9.0",
+    "genmix": "^1.2.5",
+    "modelmix": "^4.6.5",
     "string-hash": "^1.1.3"
   },
   "scripts": {

package/pnpm-workspace.yaml

@@ -1,10 +1,10 @@
 allowBuilds:
   sharp: true
-overrides:
-  ip-address: 10.1.1
 minimumReleaseAgeExclude:
-  - fast-uri@3.1.1 || 3.1.2
-  - hono@4.12.16 || 4.12.18 || 4.12.21 || 4.12.25
-  - ip-address@10.1.1
-  - ws@8.20.1 || 8.21.0
-  - qs@6.15.2
+  - genmix@1.2.5
+  - deepbase-json@3.9.0
+  - deepbase@3.9.0
+overrides:
+  sharp: "^0.35.0"
+  "@hono/node-server": "^2.0.5"
+  ip-address: ">=10.1.1"

package/skills/gptrans/SKILL.md

@@ -82,7 +82,9 @@ You can manually edit translation files to override specific entries.
 ```javascript
 import GPTrans from 'gptrans';
 
+const dbPath = new URL('./db', import.meta.url).pathname;
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en-US',
   target: 'es-AR',
   model: 'sonnet45'
@@ -119,7 +121,7 @@ console.log(gptrans.setContext().t('Welcome back'));
 ### Translate text with parameter substitution
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
 console.log(gptrans.t('Hello, {name}!', { name: 'Martin' }));
 // First call: "Hello, Martin!" (original)
 // After caching: "Hola, Martin!" (translated)
@@ -129,6 +131,7 @@ console.log(gptrans.t('Hello, {name}!', { name: 'Martin' }));
 
 ```javascript
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en',
   target: 'fr',
   model: ['sonnet45', 'gpt41']  // falls back to gpt41 if sonnet45 fails
@@ -138,7 +141,7 @@ const gptrans = new GPTrans({
 ### Pre-translate all pending texts
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es' });
 
 // Register texts
 gptrans.t('Welcome');
@@ -157,7 +160,7 @@ console.log(gptrans.t('Welcome'));  // "Bienvenido"
 Use existing translations in other languages as context for better accuracy:
 
 ```javascript
-const gptrans = new GPTrans({ from: 'es', target: 'fr' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'fr' });
 await gptrans.preload({
   references: ['en', 'pt']  // AI sees English and Portuguese as reference
 });
@@ -168,7 +171,7 @@ await gptrans.preload({
 Translate from an intermediate language instead of the original (useful for gender-neutral intermediaries):
 
 ```javascript
-const gptrans = new GPTrans({ from: 'es', target: 'pt' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'pt' });
 await gptrans.preload({
   baseLanguage: 'en',       // translate FROM English instead of Spanish
   references: ['es']        // show original Spanish for context
@@ -178,7 +181,7 @@ await gptrans.preload({
 ### Set context for gender-aware translations
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
 
 // Context applies to next translation(s) in the batch
 console.log(gptrans.setContext('The user is female').t('You are welcome'));
@@ -191,6 +194,7 @@ console.log(gptrans.setContext().t('Thank you'));
 
 ```javascript
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en', target: 'es-AR',
   instruction: 'Use a formal and professional tone'
 });
@@ -203,7 +207,7 @@ console.log(gptrans.t('Welcome to our platform'));
 Improve cached translations with specific instructions:
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
 
 // Single instruction
 await gptrans.refine('Use a more colloquial tone');
@@ -224,7 +228,7 @@ await gptrans.refine('More formal', { promptFile: './my-refine-prompt.md' });
 Requires `GEMINI_API_KEY`. Auto-detects language folders for output path:
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es' });
 
 // en/banner.jpg → es/banner.jpg (auto sibling folder)
 const translatedPath = await gptrans.img('en/banner.jpg');
@@ -240,7 +244,7 @@ const result = await gptrans.img('en/hero.jpg', {
 ### Freeze mode (prevent new translations)
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es', freeze: true });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es', freeze: true });
 
 // Returns original text, logs "[key] text" — nothing queued
 console.log(gptrans.t('New text'));
@@ -262,6 +266,7 @@ await gptrans.purge();
 ```javascript
 // Spain Spanish → Argentina Spanish
 const es2ar = new GPTrans({
+  path: dbPath,
   from: 'es-ES',
   target: 'es-AR',
   model: 'sonnet45'
@@ -301,7 +306,7 @@ if (GPTrans.isLanguageAvailable('pt-BR')) {
 
 | Method | Returns | Description |
 | --- | --- | --- |
-| `new GPTrans(options)` | `GPTrans` | Create instance with `from`, `target`, `model`, etc. |
+| `new GPTrans(options)` | `GPTrans` | Create an instance. `options.path` must be an absolute directory path. |
 | `.t(text, params?)` | `string` | Translate text (sync). Returns cached or original. |
 | `.get(key, text)` | `string \| undefined` | Get translation by key, queue if missing. |
 | `.setContext(context?)` | `this` | Set context for next batch (gender, tone, etc.). |

package/test/gptrans.batch.test.js

@@ -1,11 +1,22 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { tmpdir } from 'node:os';
 import GPTrans from '../index.js';
 
 function createMemoryDb() {
     const store = new Map();
     return {
-        get(context, key) {
+        getSync(...keys) {
+            if (keys.length === 0) {
+                return Object.fromEntries(Array.from(store.entries()).map(([context, pairs]) => [
+                    context,
+                    Object.fromEntries(pairs.entries())
+                ]));
+            }
+            const [context, key] = keys;
+            if (keys.length === 1) {
+                return Object.fromEntries(store.get(context)?.entries() ?? []);
+            }
             return store.get(context)?.get(key);
         },
         set(context, key, value) {
@@ -35,6 +46,7 @@ function createTestInstance() {
         target: 'en-US',
         debounceTimeout: 10_000,
         batchThreshold: 50_000,
+        path: tmpdir(),
         name: `unit_${Date.now()}_${Math.random().toString(36).slice(2)}`
     });
 
@@ -63,9 +75,9 @@ test('_processBatch splits correctly with \\n------\\n separators', async (t) =>
     await gp._processBatch('');
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Goodbye');
-    assert.equal(gp.dbTarget.get(h, 'k3'), 'Thank you');
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Goodbye');
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), 'Thank you');
 
     GPTrans.mmix = originalMmix;
 });
@@ -86,9 +98,9 @@ test('_processBatch falls back to split by divider without newlines', async (t)
     await gp._processBatch('');
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Goodbye');
-    assert.equal(gp.dbTarget.get(h, 'k3'), 'Thank you');
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Goodbye');
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), 'Thank you');
 
     GPTrans.mmix = originalMmix;
 });
@@ -149,10 +161,10 @@ test('_processBatch discards batch when all translations are identical (3+)', as
 
     const h = gp._hash('');
     // Nothing should be saved
-    assert.equal(gp.dbTarget.get(h, 'k1'), undefined);
-    assert.equal(gp.dbTarget.get(h, 'k2'), undefined);
-    assert.equal(gp.dbTarget.get(h, 'k3'), undefined);
-    assert.equal(gp.dbTarget.get(h, 'k4'), undefined);
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), undefined);
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), undefined);
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), undefined);
+    assert.equal(gp.dbTarget.getSync(h, 'k4'), undefined);
 
     assert.ok(errors.some(e => e.includes('translations are identical')));
 
@@ -174,8 +186,8 @@ test('_processBatch allows batch of 2 with identical translations (edge case)',
     await gp._processBatch('');
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Yes');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Yes');
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Yes');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Yes');
 
     GPTrans.mmix = originalMmix;
 });
@@ -196,9 +208,9 @@ test('_processBatch saves partial duplicates normally', async (t) => {
     await gp._processBatch('');
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k3'), 'Goodbye');
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), 'Goodbye');
 
     GPTrans.mmix = originalMmix;
 });
@@ -227,9 +239,9 @@ test('_processBatch saves partial results on count mismatch', async (t) => {
     console.error = origError;
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Goodbye');
-    assert.equal(gp.dbTarget.get(h, 'k3'), undefined); // Not saved
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Goodbye');
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), undefined); // Not saved
 
     assert.ok(errors.some(e => e.includes('Translation count mismatch')));
 

package/test/gptrans.tAsync.test.js

@@ -1,11 +1,24 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 import GPTrans from '../index.js';
 
 function createMemoryDb() {
     const store = new Map();
     return {
-        get(context, key) {
+        getSync(...keys) {
+            if (keys.length === 0) {
+                return Object.fromEntries(Array.from(store.entries()).map(([context, pairs]) => [
+                    context,
+                    Object.fromEntries(pairs.entries())
+                ]));
+            }
+            const [context, key] = keys;
+            if (keys.length === 1) {
+                return Object.fromEntries(store.get(context)?.entries() ?? []);
+            }
             return store.get(context)?.get(key);
         },
         set(context, key, value) {
@@ -39,6 +52,7 @@ function createTestInstance() {
         target: 'es',
         debounceTimeout: 10_000,
         batchThreshold: 5000,
+        path: tmpdir(),
         name: `unit_${Date.now()}_${Math.random().toString(36).slice(2)}`
     });
 
@@ -131,7 +145,7 @@ test('preload translates missing keys from dbFrom into dbTarget', async () => {
         await gp.preload();
 
         assert.equal(translateCalls, 1);
-        assert.equal(gp.dbTarget.get(contextHash, key), 'Comprar ahora');
+        assert.equal(gp.dbTarget.getSync(contextHash, key), 'Comprar ahora');
         assert.deepEqual(gp.preloadReferences, []);
         assert.equal(gp.preloadBaseLanguage, null);
     } finally {
@@ -141,3 +155,51 @@ test('preload translates missing keys from dbFrom into dbTarget', async () => {
         }
     }
 });
+
+test('constructor requires an absolute database path', () => {
+    assert.throws(() => new GPTrans(), /requires an absolute "path" option/);
+    assert.throws(() => new GPTrans({ path: './db' }), /requires an absolute "path" option/);
+});
+
+test('DeepBase 3.9 cache is available to synchronous translations', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'gptrans-deepbase-'));
+    const originalMmix = GPTrans.mmix;
+    const gp = new GPTrans({
+        from: 'en',
+        target: 'es',
+        freeze: true,
+        debounceTimeout: 1,
+        path: directory,
+        name: 'sync-cache'
+    });
+
+    try {
+        const text = 'Hello';
+        const key = gp._textToKey(text);
+        const contextHash = gp._hash('');
+        await gp.dbTarget.set(contextHash, key, 'Hola');
+
+        assert.equal(gp.t(text), 'Hola');
+        assert.equal(gp.dbTarget.getSync(contextHash, key), 'Hola');
+
+        gp.setFreeze(false);
+        const sourceText = 'New source text';
+        const sourceKey = gp._textToKey(sourceText);
+        gp._translate = async () => 'Nuevo texto fuente';
+        GPTrans.mmix = () => ({ limiter: { updateSettings() {} } });
+
+        gp.t(sourceText);
+        await gp.preload();
+
+        assert.equal(gp.dbFrom.getSync('', sourceKey), sourceText);
+        assert.equal(gp.dbTarget.getSync(contextHash, sourceKey), 'Nuevo texto fuente');
+    } finally {
+        GPTrans.mmix = originalMmix;
+        if (gp.debounceTimer) {
+            clearTimeout(gp.debounceTimer);
+        }
+        await gp.dbTarget.dispose({ clearMemory: true, releaseInstance: true });
+        await gp.dbFrom.dispose({ clearMemory: true, releaseInstance: true });
+        await rm(directory, { recursive: true });
+    }
+});

package/test-image-translation.js

@@ -12,6 +12,7 @@ async function testImageTranslation() {
 
         // Initialize GPTrans with Portuguese as target language
         const gptrans = new GPTrans({
+            path: path.join(__dirname, 'db'),
             from: 'en-US',
             target: 'pt-BR',
             model: 'sonnet45'
@@ -67,4 +68,3 @@ async function testImageTranslation() {
 
 // Run the test
 testImageTranslation();
-