@voilabs/oilang 0.0.4 → 0.0.5

package/README.md

@@ -43,16 +43,17 @@ async function main() {
     await oilang.init();
 
     // Create a new locale
-    await oilang.createLocale("en-US", "English (US)", "English");
+    await oilang.locales.create("en-US", "English (US)", "English");
 
     // Add a translation key
-    await oilang.addTranslation("en-US", {
+    await oilang.translations.create("en-US", {
         key: "greeting",
         value: "Hello, World!",
     });
 
     // Retrieve translations
-    const translations = await oilang.getAllTranslations("en-US");
+    // Example: Translations are stored in memory or Redis as a key-value pair.
+    const translations = await oilang.translations.list("en-US");
     console.log(translations);
 }
 
@@ -63,7 +64,7 @@ main();
 
 ### OILang
 
-The main entry point for the library. It orchestrates the interaction between the database adapter and the store.
+The main entry point for the library. It orchestrates the interaction between the database adapter and the store, delegating specific operations to `locales` and `translations` namespaces.
 
 #### Constructor
 
@@ -78,21 +79,50 @@ new OILang(config: AdapterConfig)
 - **`init(): Promise<void>`**
   Connects to the database and initializes the store by loading existing locales and translations.
 
-- **`createLocale(locale: string, nativeName: string, englishName: string): Promise<Result<Locale>>`**
+#### Namespaces
+
+- **`oilang.locales`**: Manages locale operations.
+- **`oilang.translations`**: Manages translation operations.
+
+### Locales
+
+Access via `oilang.locales`.
+
+#### Methods
+
+- **`list(): Promise<ActionResponse<LocaleData[]>>`**
+  Retrieves all available locales from the store.
+
+- **`create(locale: string, nativeName: string, englishName: string): Promise<ActionResponse<LocaleData>>`**
   Creates a new locale in the database and updates the store.
 
-- **`deleteLocale(locale: string): Promise<Result<Locale>>`**
+- **`delete(locale: string): Promise<ActionResponse<LocaleData>>`**
   Deletes a locale and its associated translations from both the database and the store.
 
-- **`addTranslation(locale: string, config: { key: string; value: string }): Promise<Result<Translation>>`**
-  Adds a translation key-value pair for a specific locale.
+- **`update(locale: string, nativeName: string, englishName: string): Promise<ActionResponse<LocaleData>>`**
+  Updates locale information in the database and store.
 
-- **`getAllLocales(): Promise<Result<Locale[]>>`**
-  Retrieves all available locales from the store.
+### Translations
+
+Access via `oilang.translations`.
 
-- **`getAllTranslations(locale: string): Promise<Record<string, string>>`**
+#### Methods
+
+- **`list(locale: string): Promise<Record<string, string>>`**
   Retrieves all translations for a specific locale from the store. Returns a key-value map.
 
+- **`create(locale: string, config: { key: string; value: string }): Promise<ActionResponse<TranslationData>>`**
+  Adds a translation key-value pair for a specific locale.
+
+- **`update(locale: string, key: string, newValue: string): Promise<ActionResponse<TranslationData>>`**
+  Updates an existing translation value.
+
+- **`delete(locale: string, key: string): Promise<ActionResponse<TranslationData>>`**
+  Deletes a translation key.
+
+- **`translate(locale: string, key: string, variables?: Record<string, string | number>): Promise<string>`**
+  Retrieves a single translation, optionally performing variable interpolation. Uses fallback locale if translation is missing.
+
 ### Adapters
 
 #### PostgreSQL
@@ -124,7 +154,7 @@ new MemoryStore();
 
 #### RedisStore
 
-Stores data in a Redis instance. essential for distributed applications or when data persistence across restarts (without DB reload) is desired.
+Stores data in a Redis instance. Essential for distributed applications or when data persistence across restarts (without DB reload) is desired.
 
 **Constructor**
 
@@ -163,5 +193,7 @@ Stores the translation strings.
 Most methods return a result object pattern to handle errors gracefully without throwing.
 
 ```typescript
-type Result<T> = { error: null; data: T } | { error: Error; data: null };
+type ActionResponse<T> =
+    | { error: Error & { code?: string }; data: null }
+    | { error: null; data: T };
 ```

package/dist/adapters/PostgreSQL.js

@@ -1,136 +1,154 @@
 import { Client } from "pg";
-export class PostgreSQL {
-    config;
+class Locales {
+    schema;
     client;
-    schemaNames;
-    constructor(config, customizationConfig) {
-        this.config = config;
-        this.client = new Client(config);
-        this.schemaNames = customizationConfig.schemaNames ?? {
-            keys: "keys",
-            locales: "locales",
-        };
+    constructor(schema, client) {
+        this.schema = schema;
+        this.client = client;
     }
-    async connect() {
-        await this.client.connect();
-        const QUERY = [
-            `CREATE SCHEMA IF NOT EXISTS ${this.schemaNames.locales};`,
-            `CREATE SCHEMA IF NOT EXISTS ${this.schemaNames.keys};`,
-            `
-                CREATE TABLE IF NOT EXISTS ${this.schemaNames.locales} (
-                    code VARCHAR(10) PRIMARY KEY,
-                    native_name VARCHAR(255) NOT NULL,
-                    english_name VARCHAR(255) NOT NULL
-                );
-            `,
-            `
-                CREATE TABLE IF NOT EXISTS ${this.schemaNames.keys} (
-                    key VARCHAR(255) NOT NULL,
-                    value TEXT NOT NULL,
-                    locale_id VARCHAR(10) NOT NULL,
-                    FOREIGN KEY (locale_id) REFERENCES ${this.schemaNames.locales}(code)
-                );
-            `,
-        ];
-        await this.client.query(QUERY.join("\n"));
-    }
-    getSchemaNames() {
-        return this.schemaNames;
+    async list() {
+        try {
+            const result = await this.client.query(`SELECT * FROM ${this.schema}`);
+            return { success: true, data: result.rows };
+        }
+        catch (error) {
+            return { success: false, error };
+        }
     }
-    async addLocale(locale, nativeName, englishName) {
+    async create(locale, nativeName, englishName) {
         try {
-            const existingLocale = await this.client.query(`SELECT * FROM ${this.schemaNames.locales} WHERE code = $1`, [locale]);
-            if (existingLocale.rows.length > 0) {
+            const existing = await this.client.query(`SELECT * FROM ${this.schema} WHERE code = $1`, [locale]);
+            if (existing.rows.length > 0) {
                 const error = new Error("Locale already exists");
                 error.code = "LOCALE_ALREADY_EXISTS";
                 throw error;
             }
-            const result = await this.client.query(`INSERT INTO ${this.schemaNames.locales} (code, native_name, english_name) VALUES ($1, $2, $3) RETURNING *`, [locale, nativeName, englishName]);
-            return {
-                success: true,
-                data: result.rows.at(0),
-            };
+            const result = await this.client.query(`INSERT INTO ${this.schema} (code, native_name, english_name) VALUES ($1, $2, $3) RETURNING *`, [locale, nativeName, englishName]);
+            return { success: true, data: result.rows[0] };
         }
         catch (error) {
-            return {
-                success: false,
-                error: error,
-            };
+            return { success: false, error };
         }
     }
-    async getAllLocales() {
+    async delete(locale) {
         try {
-            const result = await this.client.query(`SELECT * FROM ${this.schemaNames.locales}`);
-            return {
-                success: true,
-                data: result.rows,
-            };
+            await this.client.query(`DELETE FROM ${this.schema} WHERE code = $1`, [locale]);
+            return { success: true, data: { code: locale } };
         }
         catch (error) {
-            return {
-                success: false,
-                error: error,
-            };
+            return { success: false, error };
         }
     }
-    async getAllTranslations() {
+    async update(locale, nativeName, englishName) {
         try {
-            const result = await this.client.query(`SELECT * FROM ${this.schemaNames.keys}`);
-            return {
-                success: true,
-                data: result.rows,
-            };
+            const result = await this.client.query(`UPDATE ${this.schema} SET native_name = $2, english_name = $3 WHERE code = $1 RETURNING *`, [locale, nativeName, englishName]);
+            if (result.rows.length === 0) {
+                const error = new Error("Locale does not exist");
+                error.code = "LOCALE_NOT_FOUND";
+                throw error;
+            }
+            return { success: true, data: result.rows[0] };
         }
         catch (error) {
-            return {
-                success: false,
-                error: error,
-            };
+            return { success: false, error: error };
         }
     }
-    async deleteLocale(locale) {
+}
+class Translations {
+    schema;
+    client;
+    localesSchema;
+    constructor(schema, client, localesSchema) {
+        this.schema = schema;
+        this.client = client;
+        this.localesSchema = localesSchema;
+    }
+    async list() {
         try {
-            await this.client.query(`DELETE FROM ${this.schemaNames.locales} WHERE code = $1`, [locale]);
-            await this.client.query(`DELETE FROM ${this.schemaNames.keys} WHERE locale_id = $1`, [locale]);
-            return {
-                success: true,
-                data: {
-                    code: locale,
-                },
-            };
+            const result = await this.client.query(`SELECT * FROM ${this.schema}`);
+            return { success: true, data: result.rows };
         }
         catch (error) {
-            return {
-                success: false,
-                error: error,
-            };
+            return { success: false, error };
         }
     }
-    async addTranslation(locale, key, value) {
+    async create(key, value, locale) {
         try {
-            const existingTranslation = await this.client.query(`SELECT * FROM ${this.schemaNames.keys} WHERE locale_id = $1 AND key = $2`, [locale, key]);
-            if (existingTranslation.rows.length > 0) {
-                const error = new Error("Translation already exists");
-                error.code = "TRANSLATION_ALREADY_EXISTS";
-                throw error;
-            }
-            const existingLocale = await this.client.query(`SELECT * FROM ${this.schemaNames.locales} WHERE code = $1`, [locale]);
-            if (existingLocale.rows.length === 0) {
+            const localeCheck = await this.client.query(`SELECT * FROM ${this.localesSchema} WHERE code = $1`, [locale]);
+            if (localeCheck.rows.length === 0) {
                 const error = new Error("Locale does not exist");
                 error.code = "LOCALE_NOT_FOUND";
                 throw error;
             }
-            const result = await this.client.query(`INSERT INTO ${this.schemaNames.keys} (locale_id, key, value) VALUES ($1, $2, $3) RETURNING *`, [locale, key, value]);
-            return {
-                success: true,
-                data: result.rows.at(0),
-            };
+            const result = await this.client.query(`INSERT INTO ${this.schema} (key, value, locale_id) VALUES ($1, $2, $3) RETURNING *`, [key, value, locale]);
+            return { success: true, data: result.rows[0] };
         }
         catch (error) {
-            return {
-                success: false,
-                error: error,
-            };
+            return { success: false, error: error };
         }
     }
+    async delete(key, locale) {
+        try {
+            await this.client.query(`DELETE FROM ${this.schema} WHERE key = $1 AND locale_id = $2`, [key, locale]);
+            return { success: true, data: { locale_id: locale, key } };
+        }
+        catch (error) {
+            return { success: false, error };
+        }
+    }
+    async update(key, value, locale) {
+        try {
+            const result = await this.client.query(`UPDATE ${this.schema} SET value = $2 WHERE key = $1 AND locale_id = $3 RETURNING *`, [key, value, locale]);
+            if (result.rows.length === 0) {
+                const error = new Error("Translation does not exist");
+                error.code = "TRANSLATION_NOT_FOUND";
+                throw error;
+            }
+            return { success: true, data: result.rows[0] };
+        }
+        catch (error) {
+            return { success: false, error: error };
+        }
+    }
+}
+export class PostgreSQL {
+    config;
+    client;
+    schemaNames;
+    locales;
+    translations;
+    constructor(config, customizationConfig) {
+        this.config = config;
+        this.client = new Client(config);
+        this.schemaNames = customizationConfig.schemaNames ?? {
+            keys: "keys",
+            locales: "locales",
+        };
+        this.locales = new Locales(this.schemaNames.locales, this.client);
+        this.translations = new Translations(this.schemaNames.keys, this.client, this.schemaNames.locales);
+    }
+    async connect() {
+        await this.client.connect();
+        const QUERY = `
+            CREATE TABLE IF NOT EXISTS ${this.schemaNames.locales} (
+                code VARCHAR(10) PRIMARY KEY,
+                native_name VARCHAR(255) NOT NULL,
+                english_name VARCHAR(255) NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+
+            CREATE TABLE IF NOT EXISTS ${this.schemaNames.keys} (
+                key VARCHAR(255) NOT NULL,
+                value TEXT NOT NULL,
+                locale_id VARCHAR(10) NOT NULL,
+                PRIMARY KEY (key, locale_id),
+                FOREIGN KEY (locale_id) REFERENCES ${this.schemaNames.locales}(code) ON DELETE CASCADE
+            );
+        `;
+        await this.client.query(QUERY);
+    }
+    getSchemaNames() {
+        return this.schemaNames;
+    }
 }

package/dist/oilang.js

@@ -1,43 +1,21 @@
-export class OILang {
-    config;
+class Locale {
     database;
     store;
-    constructor(config) {
-        this.config = config;
-        this.database = config.database;
-        this.store = config.store;
+    constructor(database, store) {
+        this.database = database;
+        this.store = store;
     }
-    async init() {
-        await this.database.connect();
-        const [locales, translations] = await Promise.all([
-            this.database.getAllLocales(),
-            this.database.getAllTranslations(),
-        ]);
-        if (locales.success && translations.success) {
-            const loadableLocales = locales.data.map((l) => ({
-                code: l.code,
-                native_name: l.native_name,
-                english_name: l.english_name,
-                created_at: l.created_at,
-                updated_at: l.updated_at,
-            }));
-            const loadableTranslations = loadableLocales.reduce((acc, l) => {
-                acc[l.code] = translations.data
-                    .filter((t) => t.locale_id === l.code)
-                    .reduce((acc, t) => {
-                    acc[t.key] = t.value;
-                    return acc;
-                }, {});
-                return acc;
-            }, {});
-            await this.store.load(loadableLocales, loadableTranslations);
-        }
-        else {
-            throw new Error("Failed to load locales or translations");
-        }
+    async list() {
+        const response = await this.store.getAll({
+            seed: "locales",
+        });
+        return {
+            error: null,
+            data: response,
+        };
     }
-    async createLocale(locale, nativeName, englishName) {
-        const response = await this.database.addLocale(locale, nativeName, englishName);
+    async create(locale, nativeName, englishName) {
+        const response = await this.database.locales.create(locale, nativeName, englishName);
         if (response.success) {
             this.store.set({
                 seed: "locales",
@@ -55,8 +33,8 @@ export class OILang {
             };
         }
     }
-    async deleteLocale(locale) {
-        const response = await this.database.deleteLocale(locale);
+    async delete(locale) {
+        const response = await this.database.locales.delete(locale);
         if (response.success) {
             this.store.remove({
                 seed: "locales",
@@ -74,24 +52,48 @@ export class OILang {
             };
         }
     }
-    async getAllLocales() {
-        const response = await this.store.getAll({
-            seed: "locales",
-        });
-        return {
-            error: null,
-            data: response,
-        };
+    async update(locale, nativeName, englishName) {
+        const response = await this.database.locales.update(locale, nativeName, englishName);
+        if (response.success) {
+            this.store.update({
+                seed: "locales",
+                code: locale,
+                locale: {
+                    native_name: nativeName,
+                    english_name: englishName,
+                },
+            });
+            return {
+                error: null,
+                data: response.data,
+            };
+        }
+        else {
+            return {
+                error: response.error,
+                data: null,
+            };
+        }
     }
-    async getAllTranslations(locale) {
+}
+class Translation {
+    database;
+    store;
+    fallbackLocale;
+    constructor(database, store, fallbackLocale) {
+        this.database = database;
+        this.store = store;
+        this.fallbackLocale = fallbackLocale;
+    }
+    async list(locale) {
         const response = await this.store.getAll({
             seed: "translations",
             locale,
         });
         return response;
     }
-    async addTranslation(locale, config) {
-        const response = await this.database.addTranslation(locale, config.key, config.value);
+    async create(locale, config) {
+        const response = await this.database.translations.create(config.key, config.value, locale);
         if (response.success) {
             this.store.set({
                 seed: "translations",
@@ -111,4 +113,112 @@ export class OILang {
             };
         }
     }
+    async update(locale, key, newValue) {
+        const response = await this.database.translations.update(key, newValue, locale);
+        if (response.success) {
+            this.store.update({
+                seed: "translations",
+                locale,
+                key,
+                value: newValue,
+            });
+            return {
+                error: null,
+                data: response.data,
+            };
+        }
+        else {
+            return {
+                error: response.error,
+                data: null,
+            };
+        }
+    }
+    async delete(locale, key) {
+        const response = await this.database.translations.delete(key, locale);
+        if (response.success) {
+            this.store.remove({
+                seed: "translations",
+                locale,
+                key,
+            });
+            return {
+                error: null,
+                data: response.data,
+            };
+        }
+        else {
+            return {
+                error: response.error,
+                data: null,
+            };
+        }
+    }
+    async translate(locale, key, variables) {
+        let translation = await this.store.get({
+            seed: "translations",
+            locale,
+            key,
+        });
+        if (!translation && this.fallbackLocale) {
+            translation = await this.store.get({
+                seed: "translations",
+                locale: this.fallbackLocale,
+                key,
+            });
+        }
+        if (!translation)
+            return key;
+        if (variables) {
+            for (const [varKey, varValue] of Object.entries(variables)) {
+                translation = translation.replace(new RegExp(`{{${varKey}}}`, "g"), String(varValue));
+            }
+        }
+        return translation;
+    }
+}
+export class OILang {
+    config;
+    database;
+    store;
+    fallbackLocale;
+    locales;
+    translations;
+    constructor(config) {
+        this.config = config;
+        this.database = config.database;
+        this.store = config.store;
+        this.fallbackLocale = config.fallbackLocale ?? "en-US";
+        this.locales = new Locale(this.database, this.store);
+        this.translations = new Translation(this.database, this.store, this.fallbackLocale);
+    }
+    async init() {
+        await this.database.connect();
+        const [locales, translations] = await Promise.all([
+            this.database.locales.list(),
+            this.database.translations.list(),
+        ]);
+        if (locales.success && translations.success) {
+            const loadableLocales = locales.data.map((l) => ({
+                code: l.code,
+                native_name: l.native_name,
+                english_name: l.english_name,
+                created_at: l.created_at,
+                updated_at: l.updated_at,
+            }));
+            const loadableTranslations = loadableLocales.reduce((acc, l) => {
+                acc[l.code] = translations.data
+                    .filter((t) => t.locale_id === l.code)
+                    .reduce((accData, t) => {
+                    accData[t.key] = t.value;
+                    return accData;
+                }, {});
+                return acc;
+            }, {});
+            await this.store.load(loadableLocales, loadableTranslations);
+        }
+        else {
+            throw new Error("Failed to load locales or translations");
+        }
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@voilabs/oilang",
     "description": "A robust internationalization (i18n) handling library designed for performance and flexibility.",
-    "version": "0.0.4",
+    "version": "0.0.5",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {