@plyaz/db 0.0.0

package/README.md

@@ -0,0 +1,169 @@
+# 📦 Plyaz Package Template
+
+This is the official Plyaz internal **package template** — used to create and maintain shared libraries across all apps and services. It provides a consistent setup for TypeScript packages, full integration with `@plyaz/devtools`.
+
+Use this when creating packages like:
+
+- `@plyaz/types`
+- `@plyaz/api`
+- `@plyaz/errors`
+- `@plyaz/web3`
+- `@plyaz/config`
+
+---
+
+## 🚀 Getting Started
+
+### 🌀 Option 1: Use GitHub Template
+
+1. Go to [@plyaz/package-template](https://github.com/Plyaz-Official/package-template).
+2. Click **"Use this template"**.
+3. Name your new repo (e.g. `@plyaz/errors`, `@plyaz/types`).
+4. Clone the repo:
+```bash
+   git clone https://github.com/Plyaz-Official/package-template.git @plyaz/types
+   cd @plyaz/types
+   pnpm install
+````
+
+### 🗂 Option 2: Manual Clone
+
+```bash
+git clone https://github.com/Plyaz-Official/package-template.git @plyaz/my-package
+cd @plyaz/my-package
+pnpm install
+```
+
+Then update:
+
+* `package.json > name` → `@plyaz/my-package`
+* `package.json > disable-publish` → Remove it
+* `README.md`, GitHub metadata, CI/CD labels
+
+---
+
+## 📦 Project Structure
+
+```
+├── src/
+│   └── index.ts        # Main entry point (exports)
+├──── test/
+│       └── index.test.ts   # Unit tests using Vitest
+├── package.json        # Package metadata
+├── tsconfig.json       # Uses @plyaz/devtools base
+├── eslint.config.mjs      # Uses @plyaz/devtools eslint rules
+├── .prettier.mjs      # Uses @plyaz/devtools formatting rules
+├── .vitest.config.mjs      # Uses @plyaz/devtools vitest config
+├── .vitest.setup.mjs      # Uses @plyaz/devtools vitest setup
+```
+
+---
+
+## 📜 Scripts & Commands
+
+```json
+{
+  "build": "tsc --build",
+  "test": "vitest run",
+  "lint": "eslint .",
+  "lint:fix": "eslint . --fix",
+  "format": "prettier --write './**/*.{ts,js,json}'",
+  "format:check": "prettier --check './**/*.{ts,js,json}'",
+  "type:check": "tsc --noEmit"
+}
+```
+
+---
+
+## 🔁 Dev Workflow
+
+### Local Linking (for active development)
+
+In the **package repo**:
+
+```bash
+pnpm build
+pnpm link --global
+```
+
+In a **consumer repo** (e.g. frontend app):
+
+```bash
+pnpm link --global @plyaz/my-package
+```
+
+### Publishing to GitHub Packages
+
+Ensure `.npmrc` in your user root exists:
+
+```npmrc
+@plyaz:registry=https://npm.pkg.github.com/
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+Then publish:
+
+```bash
+pnpm publish --access=restricted
+```
+
+---
+
+## ✅ Best Practices
+
+* Always export from `src/index.ts`
+* Use semver (`1.2.0`) and follow changelog conventions
+* Keep isolated logic: packages should not import from app-specific code
+* Use `@plyaz/devtools` for all configs: ESLint, Prettier, TS, Vitest, CI and other configs
+* Include unit tests via `vitest`
+* Enable CI/CD via GitHub Actions template (see `.github/workflows/publish.yml`, `.github/workflows/security.yml`, `.github/workflows/deploy.yml`)
+
+---
+
+## 🧰 Shared Tooling
+
+This template is pre-integrated with:
+
+* ✅ TypeScript (strict mode)
+* ✅ ESLint & Prettier via `@plyaz/devtools`
+* ✅ Unit testing (Vitest)
+* ✅ CI-ready for GitHub Actions
+* ✅ `.npmrc` for GitHub Package Registry
+
+For full integration, ensure you're using the latest `@plyaz/devtools` and follow the [Plyaz Confluence Documentation](https://plyaz.atlassian.net/wiki/spaces/SD/overview).
+
+---
+
+## 🔐 GitHub Secrets (Required)
+
+To enable private publishing via CI/CD, set the following in your GitHub repo secrets:
+
+```env
+GITHUB_TOKEN=<automatically available>
+```
+
+---
+
+## 📄 When to Use a Shared Package
+
+Use this template if your logic or types:
+
+* Are used by 2+ apps/services
+* Need semantic versioning and reuse
+* Should remain independently tested and documented
+
+For example:
+
+| Package         | Description                                 |
+| --------------- | ------------------------------------------- |
+| `@plyaz/types`  | Global TypeScript types and interfaces      |
+| `@plyaz/api`    | Shared API SDK and HTTP clients             |
+| `@plyaz/errors` | Standardized error shapes and handlers      |
+| `@plyaz/web3`   | Web3 interaction layer (wallets, contracts) |
+| `@plyaz/config` | Shared config/env/constants (no logic)      |
+
+---
+
+## 🧠 Ownership
+
+This repo is managed by the Plyaz engineering team. Please follow versioning, changelog, and testing requirements when contributing.

package/dist/adapters/drizzle/DrizzleAdapter.d.ts

@@ -0,0 +1,269 @@
+import type { DrizzleAdapterConfig, DatabaseAdapterType, DatabaseResult, PaginatedResult, QueryOptions, DatabaseHealthStatus, Filter, Transaction } from "@plyaz/types/db";
+/**
+ * @class DrizzleAdapter
+ * @implements {DatabaseAdapterType}
+ * @classdesc
+ * A PostgreSQL database adapter built on top of Drizzle ORM.
+ * Provides generic CRUD operations, pagination, filtering, sorting,
+ * and transactional support with a consistent result structure.
+ */
+export declare class DrizzleAdapter implements DatabaseAdapterType {
+    private db;
+    private pool;
+    private config;
+    private tableMap;
+    private idColumnMap;
+    /**
+     * Creates a new DrizzleAdapter instance.
+     * @param {DrizzleAdapterConfig} config - Configuration object for Drizzle and PostgreSQL connection.
+     * @description
+     * Initializes the adapter with the provided configuration, setting up the connection pool
+     * and creating a Drizzle ORM instance. The configuration should include a connection string
+     * and optional pool settings such as min/max connections and idle timeout.
+     */
+    constructor(config: DrizzleAdapterConfig);
+    /**
+     * Initializes the adapter by verifying database connectivity.
+     * @returns {Promise<DatabaseResult<void>>} Success or failure result.
+     * @description
+     * Attempts to establish a connection to the database to verify that the adapter
+     * can communicate with the database. This is typically called during application startup
+     * to ensure the database is accessible before performing any operations.
+     * Returns a success result if the connection is established, or a failure result with an error
+     * if the connection cannot be established.
+     */
+    initialize(): Promise<DatabaseResult<void>>;
+    /**
+     * Opens a new connection to the database.
+     * @returns {Promise<void>}
+     * @description
+     * Establishes a connection to the PostgreSQL database using the connection pool.
+     * This method is called to ensure that a connection is available before performing database operations.
+     * The connection pool manages the connections efficiently, reusing them when possible.
+     */
+    connect(): Promise<void>;
+    /**
+     * Closes all open connections and shuts down the connection pool.
+     * @returns {Promise<void>}
+     * @description
+     * Gracefully shuts down the connection pool, closing all active connections.
+     * This method should be called when the adapter is no longer needed, typically during
+     * application shutdown, to free up database resources and prevent connection leaks.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Gets the underlying Drizzle client instance.
+     * @returns {TClient} The internal Drizzle client.
+     * @description
+     * This method exposes the internal Drizzle client instance. Direct access is discouraged
+     * to maintain abstraction and ensure all database operations go through the adapter’s
+     * interface for error handling, logging, and event emission.
+     */
+    getClient<TClient extends object = object>(): TClient;
+    /**
+     * Executes a raw SQL query.
+     * @template T - The expected type of the query result rows.
+     * @param {string} sql - Raw SQL query string.
+     * @param {T[]} [params] - Optional query parameters.
+     * @returns {Promise<T[]>} Array of query result rows.
+     * @throws {DatabaseError} When query execution fails.
+     * @description
+     * Executes a raw SQL query against the database, with optional parameterization.
+     * This method is useful for complex queries that cannot be easily expressed using the ORM
+     * or for database-specific operations. The method uses parameterized queries to prevent
+     * SQL injection attacks. If the query execution fails, a DatabaseError is thrown.
+     */
+    query<T>(sql: string, params?: T[]): Promise<T[]>;
+    /**
+     * Registers a table and optional ID column for ORM operations.
+     * @template TTable - Type representing the table structure.
+     * @template TIdColumn - Type representing the ID column.
+     * @param {string} name - Logical name of the table.
+     * @param {TTable} table - Drizzle table object.
+     * @param {TIdColumn} [idColumn] - Optional primary key column.
+     * @description
+     * Registers a table with the adapter, allowing it to be referenced by a logical name
+     * in subsequent operations. This is necessary for the adapter to perform ORM operations
+     * on the table. The ID column can also be specified if it differs from the default 'id'.
+     * This registration enables the adapter to map logical table names to actual table objects
+     * and ID columns, providing a layer of abstraction between the application and the database schema.
+     */
+    registerTable<TTable, TIdColumn>(name: string, table: TTable, idColumn?: TIdColumn): void;
+    /**
+     * Finds a record by its primary ID.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<T | null>>} Found record or null.
+     * @description
+     * Retrieves a single record from the specified table using its primary ID.
+     * The method uses the registered table and ID column to construct the query.
+     * If the record is found, it is returned in a success result. If no record is found,
+     * null is returned in a success result. If an error occurs during the operation,
+     * a failure result with an error message is returned.
+     */
+    findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>>;
+    /**
+     * Retrieves multiple records with optional filtering, sorting, and pagination.
+     * @template T - The expected type of the records.
+     * @param {string} table - Table name.
+     * @param {QueryOptions} [options] - Optional filter, sort, and pagination options.
+     * @returns {Promise<DatabaseResult<PaginatedResult<T>>>} Paginated result set.
+     * @description
+     * Retrieves multiple records from the specified table with support for filtering,
+     * sorting, and pagination. The method first applies any filters to narrow down the result set,
+     * then applies sorting to order the results, and finally applies pagination to limit the number
+     * of records returned. The result includes the data array, total count of matching records,
+     * and pagination metadata such as current page, total pages, and next/previous cursors.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    findMany<T>(table: string, options?: QueryOptions): Promise<DatabaseResult<PaginatedResult<T>>>;
+    /**
+     * Inserts a new record into the specified table.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {T} data - Record to insert.
+     * @returns {Promise<DatabaseResult<T>>} Inserted record.
+     * @description
+     * Inserts a new record into the specified table using the provided data.
+     * The method uses the registered table to construct the insert query.
+     * After insertion, it returns the inserted record with any auto-generated fields
+     * (like IDs) populated. If an error occurs during the operation,
+     * a failure result with an error message is returned.
+     */
+    create<T>(table: string, data: T): Promise<DatabaseResult<T>>;
+    /**
+     * Updates an existing record by ID.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @param {Partial<T>} data - Partial object containing fields to update.
+     * @returns {Promise<DatabaseResult<T>>} Updated record.
+     * @description
+     * Updates an existing record in the specified table using its primary ID.
+     * Only the fields provided in the data object are updated, allowing for partial updates.
+     * The method uses the registered table and ID column to construct the update query.
+     * After updating, it returns the updated record. If an error occurs during the operation,
+     * a failure result with an error message is returned.
+     */
+    update<T>(table: string, id: string, data: Partial<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Deletes a record by ID.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<void>>}
+     * @description
+     * Deletes a record from the specified table using its primary ID.
+     * The method uses the registered table and ID column to construct the delete query.
+     * If the operation is successful, it returns a success result with no value.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    delete(table: string, id: string): Promise<DatabaseResult<void>>;
+    /**
+     * Executes a transactional operation with rollback on failure.
+     * @template T - The expected type of the transaction result.
+     * @param {(trx: Transaction) => Promise<T>} callback - Function executed within a transaction.
+     * @returns {Promise<DatabaseResult<T>>} Transaction result.
+     * @description
+     * Executes a callback function within a database transaction, providing atomicity.
+     * If the callback function executes successfully, the transaction is committed.
+     * If an error occurs during the execution of the callback function, the transaction
+     * is rolled back, ensuring that no partial changes are applied to the database.
+     * The method returns the result of the callback function if successful,
+     * or a failure result with an error message if an error occurs.
+     */
+    transaction<T>(callback: (trx: Transaction) => Promise<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Checks if a record exists by ID.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<boolean>>} True if exists, otherwise false.
+     * @description
+     * Checks if a record with the specified ID exists in the table.
+     * The method uses the registered table and ID column to construct the query.
+     * It returns a success result with a boolean value indicating whether the record exists.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    exists(table: string, id: string): Promise<DatabaseResult<boolean>>;
+    /**
+     * Counts records matching an optional filter.
+     * @param {string} table - Table name.
+     * @param {Filter} [filter] - Optional filter object.
+     * @returns {Promise<DatabaseResult<number>>} Total count of matching records.
+     * @description
+     * Counts the number of records in the specified table that match the optional filter.
+     * The method uses the registered table to construct the count query.
+     * If a filter is provided, it is applied to narrow down the count to matching records.
+     * It returns a success result with the count of matching records.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    count(table: string, filter?: Filter): Promise<DatabaseResult<number>>;
+    /**
+     * Performs a health check on the database connection.
+     * @returns {Promise<DatabaseResult<DatabaseHealthStatus>>} Health status with response time.
+     * @description
+     * Checks the health of the database connection by executing a simple query.
+     * The method measures the response time of the query to determine the health status.
+     * It returns a success result with a HealthStatus object indicating whether the database is healthy,
+     * the response time of the health check, and any additional details.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    healthCheck(): Promise<DatabaseResult<DatabaseHealthStatus>>;
+    /**
+     * Retrieves a registered table by name.
+     * @private
+     * @param {string} name - Table name.
+     * @returns {PgTable} Table object.
+     * @throws {DatabaseError} If table is not registered.
+     * @description
+     * Retrieves a table object that has been previously registered with the adapter.
+     * This method is used internally by other methods to ensure that operations are performed
+     * on valid, registered tables. If the table is not found, it throws a DatabaseError.
+     */
+    private getTable;
+    /**
+     * Retrieves the registered ID column for a table.
+     * @private
+     * @param {string} name - Table name.
+     * @returns {PgColumn} ID column.
+     * @throws {DatabaseError} If ID column is not registered.
+     * @description
+     * Retrieves the ID column that has been previously registered for a table.
+     * This method is used internally by other methods to ensure that operations that require
+     * the ID column can access it. If the ID column is not found, it throws a DatabaseError.
+     */
+    private getIdColumn;
+    /**
+     * Builds a SQL `WHERE` clause based on filter operators.
+     * @private
+     * @param {Filter} filter - Filter definition.
+     * @param {PgTable} table - Table to apply filter on.
+     * @returns {SQL | undefined} SQL condition object.
+     * @throws {DatabaseError} If column or operator is invalid.
+     * @description
+     * Builds a SQL WHERE clause based on the provided filter definition.
+     * It supports various operators like equality, comparison, and null checks.
+     * If the column specified in the filter does not exist in the table, or if the operator
+     * is not supported, it throws a DatabaseError. The method returns an SQL object that
+     * can be used in queries, or undefined if no valid clause can be constructed.
+     */
+    private buildWhereClause;
+    /**
+     * Applies sorting to a query using provided field and direction.
+     * @private
+     * @template TQuery - Type of the query builder.
+     * @template TTable - Type of the table.
+     * @param {TQuery} query - Drizzle query builder.
+     * @param {SortOptions[]} sort - Array of sort conditions.
+     * @param {TTable} table - Target table.
+     * @returns {TQuery} Modified query with applied sorting.
+     * @throws {DatabaseError} If field is invalid or missing.
+     * @description
+     * Applies sorting to a Drizzle query based on the provided sort options.
+     * It supports sorting by multiple fields in ascending or descending order.
+     * If a field specified in the sort options does not exist in the table, or is not a valid column,
+     * it throws a DatabaseError. The method returns the modified query with the sorting applied.
+     */
+    private applySorting;
+}
+//# sourceMappingURL=DrizzleAdapter.d.ts.map

package/dist/adapters/drizzle/DrizzleAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DrizzleAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/drizzle/DrizzleAdapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Database adapter implementations
+ * @module adapters
+ */
+/**
+ * Drizzle ORM adapter for PostgreSQL databases
+ * @exports DrizzleAdapter
+ */
+export { DrizzleAdapter } from "./drizzle/DrizzleAdapter";
+/**
+ * Supabase adapter for PostgreSQL databases
+ * @exports SupabaseAdapter
+ */
+export { SupabaseAdapter } from "./supabase/SupabaseAdapter";
+/**
+ * Plain SQL adapter for PostgreSQL databases
+ * @exports SQLAdapter
+ */
+export { SQLAdapter } from "./sql/SQLAdapter";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}