@voilabs/oilang 0.0.1

package/README.md

@@ -0,0 +1,167 @@
+# OILang
+
+OILang is a robust internationalization (i18n) handling library designed for performance and flexibility. It employs a dual-layer architecture, utilizing a persistent database as the source of truth and a high-performance in-memory or Redis-based store for fast runtime access. This ensures that your application remains responsive while maintaining data integrity and persistence.
+
+## Features
+
+- **Dual-Layer Architecture**: Combines persistent storage with fast caching.
+- **Flexible Storage**: Choose between in-memory storage for simple use cases or Redis for distributed systems.
+- **Customizable Schemas**: Configurable database schema names to fit existing database structures.
+- **Type-Safe**: Built with TypeScript for reliable development.
+
+## Installation
+
+To use OILang, you need to install the package and its peer dependencies.
+
+```bash
+bun add @voilabs/oilang
+```
+
+## Usage
+
+Here is a basic example of how to initialize and use OILang within your application.
+
+```typescript
+import { OILang, PostgreSQL, MemoryStore } from "@voilabs/oilang";
+
+// Initialize the library
+const oilang = new OILang({
+    database: new PostgreSQL(
+        "postgresql://user:password@localhost:5432/dbname",
+        {
+            schemaNames: {
+                keys: "i18n_keys",
+                locales: "i18n_locales",
+            },
+        },
+    ),
+    store: new MemoryStore(),
+});
+
+async function main() {
+    // Connect to database and load data into store
+    await oilang.init();
+
+    // Create a new locale
+    await oilang.createLocale("en-US", "English (US)", "English");
+
+    // Add a translation key
+    await oilang.addTranslation("en-US", {
+        key: "greeting",
+        value: "Hello, World!",
+    });
+
+    // Retrieve translations
+    const translations = await oilang.getAllTranslations("en-US");
+    console.log(translations);
+}
+
+main();
+```
+
+## API Reference
+
+### OILang
+
+The main entry point for the library. It orchestrates the interaction between the database adapter and the store.
+
+#### Constructor
+
+```typescript
+new OILang(config: AdapterConfig)
+```
+
+- `config`: Configuration object containing initialized `database` and `store` instances.
+
+#### Methods
+
+- **`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>>`**
+  Creates a new locale in the database and updates the store.
+
+- **`deleteLocale(locale: string): Promise<Result<Locale>>`**
+  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.
+
+- **`getAllLocales(): Promise<Result<Locale[]>>`**
+  Retrieves all available locales from the store.
+
+- **`getAllTranslations(locale: string): Promise<Record<string, string>>`**
+  Retrieves all translations for a specific locale from the store. Returns a key-value map.
+
+### Adapters
+
+#### PostgreSQL
+
+Handles persistent storage of locales and translations.
+
+**Constructor**
+
+```typescript
+new PostgreSQL(connectionString: string | ClientConfig, config: { schemaNames: { keys: string; locales: string } })
+```
+
+- `connectionString`: PostgreSQL connection string or configuration object.
+- `config.schemaNames`: Custom table names for keys and locales.
+
+### Stores
+
+Stores handle the runtime access to data. They act as a cache that is synchronized with the database.
+
+#### MemoryStore
+
+Stores data in the application's memory. Suitable for single-instance applications or development.
+
+**Constructor**
+
+```typescript
+new MemoryStore();
+```
+
+#### RedisStore
+
+Stores data in a Redis instance. essential for distributed applications or when data persistence across restarts (without DB reload) is desired.
+
+**Constructor**
+
+```typescript
+new RedisStore(connectionString: string, options?: { prefix?: string })
+```
+
+- `connectionString`: Redis connection URL (default: `redis://localhost:6379`).
+- `options.prefix`: specific prefix for Redis keys (default: `oilang:`).
+
+## Database Schema
+
+The PostgreSQL adapter automatically creates the necessary tables if they do not exist.
+
+### Locales Table
+
+Stores information about supported languages.
+
+- `code` (Primary Key): The locale code (e.g., "en-US").
+- `native_name`: Name of the language in its own script.
+- `english_name`: Name of the language in English.
+- `created_at`: Timestamp of creation.
+- `updated_at`: Timestamp of last update.
+
+### Keys Table
+
+Stores the translation strings.
+
+- `id` (Primary Key): Unique identifier.
+- `key`: The translation key (e.g., "homepage.title").
+- `value`: The translated string.
+- `locale_id` (Foreign Key): References `Locales(code)`.
+
+## Return Types
+
+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 };
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@voilabs/oilang",
+    "description": "A robust internationalization (i18n) handling library designed for performance and flexibility.",
+    "version": "0.0.1",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "devDependencies": {
+        "@types/bun": "latest",
+        "@types/node": "^25.2.3",
+        "@types/pg": "^8.16.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "peerDependencies": {
+        "typescript": "^5.9.3"
+    },
+    "homepage": "https://oilang.com",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/voilabs/node-oilang.git"
+    },
+    "dependencies": {
+        "ioredis": "^5.9.3",
+        "pg": "^8.18.0"
+    }
+}

package/src/adapters/PostgreSQL.ts

@@ -0,0 +1,240 @@
+import { Client, type ClientConfig } from "pg";
+
+export class PostgreSQL {
+    client: Client;
+    schemaNames: { keys: string; locales: string };
+
+    constructor(
+        private config: string | ClientConfig | undefined,
+        customizationConfig: {
+            schemaNames: { keys: string; locales: string };
+        },
+    ) {
+        this.client = new Client(config);
+        this.schemaNames = customizationConfig.schemaNames ?? {
+            keys: "keys",
+            locales: "locales",
+        };
+    }
+
+    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 addLocale(
+        locale: string,
+        nativeName: string,
+        englishName: string,
+    ): Promise<
+        | {
+              success: true;
+              data: {
+                  code: string;
+                  native_name: string;
+                  english_name: string;
+                  created_at: string;
+                  updated_at: string;
+              };
+          }
+        | {
+              success: false;
+              error: any;
+          }
+    > {
+        try {
+            const existingLocale = await this.client.query(
+                `SELECT * FROM ${this.schemaNames.locales} WHERE code = $1`,
+                [locale],
+            );
+
+            if (existingLocale.rows.length > 0) {
+                const error = new Error("Locale already exists");
+                (error as any).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),
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error,
+            };
+        }
+    }
+
+    async getAllLocales(): Promise<
+        | {
+              success: true;
+              data: Array<{
+                  code: string;
+                  native_name: string;
+                  english_name: string;
+                  created_at: string;
+                  updated_at: string;
+              }>;
+          }
+        | {
+              success: false;
+              error: any;
+          }
+    > {
+        try {
+            const result = await this.client.query(
+                `SELECT * FROM ${this.schemaNames.locales}`,
+            );
+            return {
+                success: true,
+                data: result.rows,
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error,
+            };
+        }
+    }
+
+    async getAllTranslations(): Promise<
+        | {
+              success: true;
+              data: Array<{
+                  locale_id: string;
+                  key: string;
+                  value: string;
+              }>;
+          }
+        | {
+              success: false;
+              error: any;
+          }
+    > {
+        try {
+            const result = await this.client.query(
+                `SELECT * FROM ${this.schemaNames.keys}`,
+            );
+            return {
+                success: true,
+                data: result.rows,
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error,
+            };
+        }
+    }
+
+    async deleteLocale(locale: string) {
+        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,
+                },
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error,
+            };
+        }
+    }
+
+    async addTranslation(
+        locale: string,
+        key: string,
+        value: string,
+    ): Promise<
+        | {
+              success: false;
+              error: Error & { code: string };
+          }
+        | {
+              success: true;
+              data: {
+                  locale_id: string;
+                  key: string;
+                  value: string;
+              };
+          }
+    > {
+        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 as any).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 error = new Error("Locale does not exist");
+                (error as any).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),
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error as Error & { code: string },
+            };
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { OILang } from "./oilang";
+export { PostgreSQL } from "./adapters/PostgreSQL";
+export { MemoryStore } from "./stores/MemoryStore";
+export { RedisStore } from "./stores/RedisStore";

package/src/oilang.ts

@@ -0,0 +1,182 @@
+import type { MemoryStore } from "./stores/MemoryStore";
+import type { PostgreSQL } from "./adapters/PostgreSQL";
+import type { RedisStore } from "./stores/RedisStore";
+
+type AdapterConfig = {
+    database: InstanceType<typeof PostgreSQL>;
+    store: InstanceType<typeof MemoryStore> | InstanceType<typeof RedisStore>;
+};
+
+export class OILang {
+    private database: AdapterConfig["database"];
+    private store: AdapterConfig["store"];
+    constructor(private config: AdapterConfig) {
+        this.database = config.database;
+        this.store = config.store;
+    }
+
+    async init(): Promise<void> {
+        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;
+                            },
+                            {} as Record<string, string>,
+                        );
+                    return acc;
+                },
+                {} as Record<string, Record<string, string>>,
+            );
+
+            await this.store.load(loadableLocales, loadableTranslations);
+        } else {
+            throw new Error("Failed to load locales or translations");
+        }
+    }
+
+    async createLocale(
+        locale: string,
+        nativeName: string,
+        englishName: string,
+    ): Promise<
+        | {
+              error: Error & { code: string };
+              data: null;
+          }
+        | {
+              error: null;
+              data: {
+                  code: string;
+                  native_name: string;
+                  english_name: string;
+                  created_at: string;
+                  updated_at: string;
+              };
+          }
+    > {
+        const response = await this.database.addLocale(
+            locale,
+            nativeName,
+            englishName,
+        );
+
+        if (response.success) {
+            this.store.set({
+                seed: "locales",
+                locale: response.data,
+            });
+
+            return {
+                error: null,
+                data: response.data,
+            };
+        } else {
+            return {
+                error: response.error,
+                data: null,
+            };
+        }
+    }
+
+    async deleteLocale(locale: string) {
+        const response = await this.database.deleteLocale(locale);
+
+        if (response.success) {
+            this.store.remove({
+                seed: "locales",
+                locale,
+            });
+            return {
+                error: null,
+                data: response.data,
+            };
+        } else {
+            return {
+                error: response.error,
+                data: null,
+            };
+        }
+    }
+
+    async getAllLocales() {
+        const response = await this.store.getAll({
+            seed: "locales",
+        });
+
+        return {
+            error: null,
+            data: response,
+        };
+    }
+
+    async getAllTranslations(locale: string) {
+        const response = await this.store.getAll({
+            seed: "translations",
+            locale,
+        });
+
+        return response;
+    }
+
+    async addTranslation(
+        locale: string,
+        config: { key: string; value: string },
+    ): Promise<
+        | {
+              error: Error & { code: string };
+              data: null;
+          }
+        | {
+              error: null;
+              data: {
+                  locale_id: string;
+                  key: string;
+                  value: string;
+              };
+          }
+    > {
+        const response = await this.database.addTranslation(
+            locale,
+            config.key,
+            config.value,
+        );
+
+        if (response.success) {
+            this.store.set({
+                seed: "translations",
+                locale,
+                key: config.key,
+                value: config.value,
+            });
+            return {
+                error: null,
+                data: response.data,
+            };
+        } else {
+            return {
+                error: response.error,
+                data: null,
+            };
+        }
+    }
+}

package/src/stores/MemoryStore.ts

@@ -0,0 +1,147 @@
+export class MemoryStore {
+    private translations: Record<string, Record<string, string>> = {};
+    private locales: Array<{
+        code: string;
+        native_name: string;
+        english_name: string;
+        created_at: string;
+        updated_at: string;
+    }> = [];
+
+    async load(
+        locales: Array<{
+            code: string;
+            native_name: string;
+            english_name: string;
+            created_at: string;
+            updated_at: string;
+        }>,
+        translations: Record<string, Record<string, string>>,
+    ) {
+        this.locales = locales;
+        this.translations = translations;
+    }
+
+    async set(
+        config:
+            | {
+                  seed: "translations";
+                  locale: string;
+                  key: string;
+                  value: string;
+              }
+            | {
+                  seed: "locales";
+                  locale: {
+                      code: string;
+                      native_name: string;
+                      english_name: string;
+                      created_at: string;
+                      updated_at: string;
+                  };
+              },
+    ) {
+        if (config.seed === "translations") {
+            (this.translations[config.locale] as any)[config.key] =
+                config.value;
+        } else {
+            this.locales.push(config.locale);
+            this.translations[config.locale.code] = {};
+        }
+    }
+
+    async get(
+        config:
+            | {
+                  seed: "locales";
+                  code: string;
+              }
+            | {
+                  seed: "translations";
+                  locale: string;
+                  key: string;
+              },
+    ) {
+        if (config.seed === "translations") {
+            return this.translations[config.locale]?.[config.key];
+        } else {
+            return this.locales.find((l) => l.code === config.code);
+        }
+    }
+
+    async getAll(
+        config:
+            | {
+                  seed: "locales";
+              }
+            | {
+                  seed: "translations";
+                  locale: string;
+              },
+    ) {
+        if (config.seed === "translations") {
+            return this.translations[config.locale];
+        } else {
+            return this.locales;
+        }
+    }
+
+    async remove(
+        config:
+            | {
+                  seed: "translations";
+                  locale: string;
+                  key: string;
+              }
+            | {
+                  seed: "locales";
+                  locale: string;
+              },
+    ) {
+        if (config.seed === "translations") {
+            if (
+                this.translations[config.locale] &&
+                this.translations[config.locale]?.[config.key]
+            ) {
+                delete this.translations[config.locale]?.[config.key];
+            }
+        } else {
+            this.locales = this.locales.filter((l) => l.code !== config.locale);
+            delete this.translations[config.locale];
+        }
+    }
+
+    async update(
+        config:
+            | {
+                  seed: "translations";
+                  locale: string;
+                  key: string;
+                  value: string;
+              }
+            | {
+                  seed: "locales";
+                  code: string;
+                  locale: {
+                      native_name: string;
+                      english_name: string;
+                      created_at: string;
+                      updated_at: string;
+                  };
+              },
+    ) {
+        if (config.seed === "translations") {
+            return this.set({
+                seed: "translations",
+                locale: config.locale,
+                key: config.key,
+                value: config.value,
+            });
+        } else {
+            this.locales = this.locales.map((l) =>
+                l.code === config.code ? { ...l, ...config.locale } : l,
+            );
+            return true;
+        }
+    }
+}

package/src/stores/RedisStore.ts

@@ -0,0 +1,205 @@
+import Redis from "ioredis";
+
+export class RedisStore {
+    private client: Redis;
+
+    constructor(
+        connectionString: string = "redis://localhost:6379",
+        private options?: { prefix?: string },
+    ) {
+        this.client = new Redis(connectionString);
+    }
+
+    private get prefix() {
+        return this.options?.prefix ?? "oilang:";
+    }
+
+    async load(
+        locales: Array<{
+            code: string;
+            native_name: string;
+            english_name: string;
+            created_at: string;
+            updated_at: string;
+        }>,
+        translations: Record<string, Record<string, string>>,
+    ) {
+        const existingLocales = await this.client.hvals(
+            `${this.prefix}locales`,
+        );
+        const pipeline = this.client.pipeline();
+
+        if (existingLocales.length > 0) {
+            existingLocales.forEach((lStr) => {
+                const l = JSON.parse(lStr);
+                pipeline.del(`${this.prefix}translations:${l.code}`);
+            });
+            pipeline.del(`${this.prefix}locales`);
+        }
+
+        if (locales.length > 0) {
+            const localeMap: Record<string, string> = {};
+            for (const locale of locales) {
+                localeMap[locale.code] = JSON.stringify(locale);
+            }
+            pipeline.hset(`${this.prefix}locales`, localeMap);
+        }
+
+        for (const [locale, trans] of Object.entries(translations)) {
+            if (Object.keys(trans).length > 0) {
+                pipeline.hset(`${this.prefix}translations:${locale}`, trans);
+            }
+        }
+
+        await pipeline.exec();
+    }
+
+    async set(
+        config:
+            | {
+                  seed: "translations";
+                  locale: string;
+                  key: string;
+                  value: string;
+              }
+            | {
+                  seed: "locales";
+                  locale: {
+                      code: string;
+                      native_name: string;
+                      english_name: string;
+                      created_at: string;
+                      updated_at: string;
+                  };
+              },
+    ) {
+        if (config.seed === "translations") {
+            await this.client.hset(
+                `${this.prefix}translations:${config.locale}`,
+                config.key,
+                config.value,
+            );
+        } else {
+            await this.client.hset(
+                `${this.prefix}locales`,
+                config.locale.code,
+                JSON.stringify(config.locale),
+            );
+        }
+    }
+
+    async get(
+        config:
+            | {
+                  seed: "locales";
+                  code: string;
+              }
+            | {
+                  seed: "translations";
+                  locale: string;
+                  key: string;
+              },
+    ) {
+        if (config.seed === "translations") {
+            const val = await this.client.hget(
+                `${this.prefix}translations:${config.locale}`,
+                config.key,
+            );
+            return val ?? undefined;
+        } else {
+            const val = await this.client.hget(
+                `${this.prefix}locales`,
+                config.code,
+            );
+            return val ? JSON.parse(val) : undefined;
+        }
+    }
+
+    async getAll(
+        config:
+            | {
+                  seed: "locales";
+              }
+            | {
+                  seed: "translations";
+                  locale: string;
+              },
+    ) {
+        if (config.seed === "translations") {
+            return await this.client.hgetall(
+                `${this.prefix}translations:${config.locale}`,
+            );
+        } else {
+            const locales = await this.client.hvals(`${this.prefix}locales`);
+            return locales.map((l: string) => JSON.parse(l));
+        }
+    }
+
+    async remove(
+        config:
+            | {
+                  seed: "translations";
+                  locale: string;
+                  key: string;
+              }
+            | {
+                  seed: "locales";
+                  locale: string;
+              },
+    ) {
+        if (config.seed === "translations") {
+            await this.client.hdel(
+                `${this.prefix}translations:${config.locale}`,
+                config.key,
+            );
+        } else {
+            const pipeline = this.client.pipeline();
+            pipeline.hdel(`${this.prefix}locales`, config.locale);
+            pipeline.del(`${this.prefix}translations:${config.locale}`);
+            await pipeline.exec();
+        }
+    }
+
+    async update(
+        config:
+            | {
+                  seed: "translations";
+                  locale: string;
+                  key: string;
+                  value: string;
+              }
+            | {
+                  seed: "locales";
+                  code: string;
+                  locale: {
+                      native_name: string;
+                      english_name: string;
+                      created_at: string;
+                      updated_at: string;
+                  };
+              },
+    ) {
+        if (config.seed === "translations") {
+            return this.set({
+                seed: "translations",
+                locale: config.locale,
+                key: config.key,
+                value: config.value,
+            });
+        } else {
+            const existingStr = await this.client.hget(
+                `${this.prefix}locales`,
+                config.code,
+            );
+            const existing = existingStr ? JSON.parse(existingStr) : {};
+            const merged = { ...existing, ...config.locale };
+
+            await this.client.hset(
+                `${this.prefix}locales`,
+                config.code,
+                JSON.stringify(merged),
+            );
+            return true;
+        }
+    }
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "Preserve",
+        "strict": true,
+        "outDir": "./dist",
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": ["src"],
+    "exclude": ["node_modules", "**/*.test.ts"]
+}