@entergreat/pg-light 1.0.0

package/example-knex.js

@@ -0,0 +1,246 @@
+import { connectDB } from './src/index.js';
+
+// Example: Using Knex Query Builder for Complex Queries
+
+async function main() {
+  // Connect to database
+  const db = await connectDB('postgresql://user:password@localhost:5432/mydb', {
+    service: 'knex-example',
+    logLevel: 'debug'
+  });
+
+  try {
+    // SIMPLE QUERIES WITH KNEX
+
+    // Select all users
+    const allUsers = await db.builder('users').select('*');
+    console.log('All users:', allUsers);
+
+    // Select with WHERE
+    const activeUsers = await db.builder('users')
+      .select('*')
+      .where({ active: true })
+      .orderBy('created_at', 'desc');
+    console.log('Active users:', activeUsers);
+
+    // Select specific columns
+    const userEmails = await db.builder('users')
+      .select('id', 'name', 'email')
+      .where('age', '>', 25)
+      .limit(10);
+    console.log('User emails:', userEmails);
+
+    // COMPLEX QUERIES
+
+    // JOIN queries
+    const postsWithAuthors = await db.builder('posts')
+      .select('posts.*', 'users.name as author_name', 'users.email as author_email')
+      .join('users', 'posts.user_id', 'users.id')
+      .where('posts.published', true)
+      .orderBy('posts.created_at', 'desc')
+      .limit(20);
+    console.log('Posts with authors:', postsWithAuthors);
+
+    // Multiple JOINs
+    const postsWithCommentsCount = await db.builder('posts')
+      .select('posts.*', 'users.name as author')
+      .count('comments.id as comment_count')
+      .leftJoin('users', 'posts.user_id', 'users.id')
+      .leftJoin('comments', 'posts.id', 'comments.post_id')
+      .groupBy('posts.id', 'users.name')
+      .having(db.knex.raw('COUNT(comments.id) > ?', [5]))
+      .orderBy('comment_count', 'desc');
+    console.log('Popular posts:', postsWithCommentsCount);
+
+    // WHERE with multiple conditions
+    const filteredUsers = await db.builder('users')
+      .select('*')
+      .where('active', true)
+      .andWhere('age', '>=', 18)
+      .andWhere('age', '<=', 65)
+      .whereIn('role', ['admin', 'moderator'])
+      .whereNotNull('email')
+      .orderBy('created_at', 'desc');
+    console.log('Filtered users:', filteredUsers);
+
+    // OR conditions
+    const searchResults = await db.builder('users')
+      .select('*')
+      .where('name', 'like', '%John%')
+      .orWhere('email', 'like', '%john%')
+      .limit(10);
+    console.log('Search results:', searchResults);
+
+    // Subqueries
+    const usersWithManyPosts = await db.builder('users')
+      .select('users.*')
+      .whereIn('users.id', function() {
+        this.select('user_id')
+          .from('posts')
+          .groupBy('user_id')
+          .havingRaw('COUNT(*) > ?', [10]);
+      });
+    console.log('Prolific authors:', usersWithManyPosts);
+
+    // AGGREGATIONS
+
+    // Count
+    const userCount = await db.builder('users').count('* as total');
+    console.log('Total users:', userCount[0].total);
+
+    // Average, Sum, Min, Max
+    const stats = await db.builder('orders')
+      .select(
+        db.knex.raw('AVG(total) as avg_order'),
+        db.knex.raw('SUM(total) as revenue'),
+        db.knex.raw('MIN(total) as min_order'),
+        db.knex.raw('MAX(total) as max_order')
+      )
+      .where('status', 'completed');
+    console.log('Order stats:', stats[0]);
+
+    // Group by with aggregation
+    const ordersByUser = await db.builder('orders')
+      .select('user_id')
+      .count('* as order_count')
+      .sum('total as total_spent')
+      .groupBy('user_id')
+      .orderBy('total_spent', 'desc')
+      .limit(10);
+    console.log('Top spenders:', ordersByUser);
+
+    // INSERT
+
+    const [newUser] = await db.builder('users')
+      .insert({
+        name: 'Alice Johnson',
+        email: 'alice@example.com',
+        age: 28,
+        active: true
+      })
+      .returning('*');
+    console.log('Created user:', newUser);
+
+    // Bulk insert
+    const newUsers = await db.builder('users')
+      .insert([
+        { name: 'Bob', email: 'bob@example.com', age: 30 },
+        { name: 'Charlie', email: 'charlie@example.com', age: 25 }
+      ])
+      .returning('*');
+    console.log('Created users:', newUsers);
+
+    // UPDATE
+
+    const updatedCount = await db.builder('users')
+      .where({ email: 'alice@example.com' })
+      .update({
+        last_login: db.knex.fn.now(),
+        login_count: db.knex.raw('login_count + 1')
+      });
+    console.log('Updated rows:', updatedCount);
+
+    // UPDATE with JOIN (PostgreSQL specific)
+    await db.knex.raw(`
+      UPDATE posts
+      SET featured = true
+      FROM users
+      WHERE posts.user_id = users.id
+        AND users.role = 'premium'
+    `);
+
+    // DELETE
+
+    const deletedCount = await db.builder('users')
+      .where('active', false)
+      .andWhere('last_login', '<', db.knex.raw("NOW() - INTERVAL '1 year'"))
+      .delete();
+    console.log('Deleted inactive users:', deletedCount);
+
+    // TRANSACTIONS WITH KNEX
+
+    await db.knex.transaction(async (trx) => {
+      // Insert user
+      const [user] = await trx('users')
+        .insert({ name: 'David', email: 'david@example.com' })
+        .returning('*');
+
+      // Insert posts for user
+      await trx('posts').insert([
+        { user_id: user.id, title: 'Post 1', content: 'Content 1' },
+        { user_id: user.id, title: 'Post 2', content: 'Content 2' }
+      ]);
+
+      // Update user stats
+      await trx('users')
+        .where({ id: user.id })
+        .update({ post_count: 2 });
+
+      console.log('Transaction completed');
+    });
+
+    // RAW QUERIES WITH KNEX
+
+    const customQuery = await db.knex.raw(`
+      SELECT u.*, COUNT(p.id) as post_count
+      FROM users u
+      LEFT JOIN posts p ON u.id = p.user_id
+      WHERE u.active = ?
+      GROUP BY u.id
+      HAVING COUNT(p.id) > ?
+      ORDER BY post_count DESC
+      LIMIT ?
+    `, [true, 5, 10]);
+    console.log('Custom query results:', customQuery.rows);
+
+    // COMBINING MODEL API WITH KNEX
+
+    const User = db.model('users');
+
+    // Simple CRUD with Model
+    const simpleUser = await User.findById(1);
+    console.log('Simple find:', simpleUser);
+
+    // Complex query with Knex
+    const complexQuery = await db.builder('users')
+      .select('users.*', db.knex.raw('COUNT(posts.id) as post_count'))
+      .leftJoin('posts', 'users.id', 'posts.user_id')
+      .where('users.active', true)
+      .groupBy('users.id')
+      .having(db.knex.raw('COUNT(posts.id) > ?'), 10)
+      .orderBy('post_count', 'desc');
+    console.log('Complex query:', complexQuery);
+
+    // PAGINATION
+
+    const page = 2;
+    const perPage = 10;
+    const offset = (page - 1) * perPage;
+
+    const paginatedResults = await db.builder('users')
+      .select('*')
+      .where({ active: true })
+      .orderBy('created_at', 'desc')
+      .limit(perPage)
+      .offset(offset);
+
+    const [{ total }] = await db.builder('users')
+      .count('* as total')
+      .where({ active: true });
+
+    console.log({
+      data: paginatedResults,
+      page,
+      perPage,
+      total,
+      totalPages: Math.ceil(total / perPage)
+    });
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    await db.disconnect();
+  }
+}
+
+main();

package/example-model.js

@@ -0,0 +1,103 @@
+import { connectDB } from './src/index.js';
+
+// Example: Mongoose-like Model API for pg-light
+
+async function main() {
+  // Connect to database
+  const db = await connectDB('postgresql://user:password@localhost:5432/mydb', {
+    service: 'model-example',
+    logLevel: 'debug'
+  });
+
+  // Create models (like Mongoose)
+  const User = db.model('users');
+  const Post = db.model('posts');
+
+  try {
+    // CREATE - Insert new records
+    const newUser = await User.create({
+      name: 'John Doe',
+      email: 'john@example.com',
+      age: 30
+    });
+    console.log('Created user:', newUser);
+
+    // FIND ALL - Get all records
+    const allUsers = await User.find();
+    console.log('All users:', allUsers);
+
+    // FIND WITH CONDITIONS - Filter records
+    const activeUsers = await User.find({ active: true });
+    console.log('Active users:', activeUsers);
+
+    // FIND WITH OPTIONS - Pagination
+    const firstTenUsers = await User.find({}, { limit: 10, offset: 0 });
+    console.log('First 10 users:', firstTenUsers);
+
+    // FIND ONE - Get single record
+    const john = await User.findOne({ email: 'john@example.com' });
+    console.log('Found John:', john);
+
+    // FIND BY ID - Get by primary key
+    const userById = await User.findById(1);
+    console.log('User #1:', userById);
+
+    // UPDATE - Update records
+    const updatedUsers = await User.update(
+      { email: 'john@example.com' },
+      { last_login: new Date() }
+    );
+    console.log('Updated users:', updatedUsers);
+
+    // UPDATE BY ID - Update single record
+    const updatedUser = await User.updateById(1, { name: 'John Smith' });
+    console.log('Updated user:', updatedUser);
+
+    // COUNT - Count records
+    const totalUsers = await User.count();
+    console.log('Total users:', totalUsers);
+
+    const activeCount = await User.count({ active: true });
+    console.log('Active users count:', activeCount);
+
+    // DELETE - Remove records
+    const deletedUsers = await User.delete({ active: false });
+    console.log('Deleted inactive users:', deletedUsers);
+
+    // DELETE BY ID - Remove single record
+    const deletedUser = await User.deleteById(999);
+    console.log('Deleted user:', deletedUser);
+
+    // RELATIONSHIPS - Create related records
+    const post = await Post.create({
+      title: 'My First Post',
+      content: 'Hello World!',
+      user_id: newUser.id,
+      published: true
+    });
+    console.log('Created post:', post);
+
+    // Find posts by user
+    const userPosts = await Post.find({ user_id: newUser.id });
+    console.log('User posts:', userPosts);
+
+    // COMPLEX QUERIES - Still use raw SQL when needed
+    const popularPosts = await db.query(
+      `SELECT p.*, u.name as author_name
+       FROM posts p
+       JOIN users u ON p.user_id = u.id
+       WHERE p.views > $1
+       ORDER BY p.views DESC
+       LIMIT $2`,
+      [1000, 10]
+    );
+    console.log('Popular posts:', popularPosts.rows);
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    await db.disconnect();
+  }
+}
+
+main();

package/example.js

@@ -0,0 +1,38 @@
+import { connectDB } from './src/index.js';
+
+// Example usage of pg-light
+
+async function main() {
+  // Connect to database (use your connection string)
+  const db = await connectDB('postgresql://user:password@localhost:5432/mydb', {
+    service: 'pg-light-example',
+    logLevel: 'debug'
+  });
+
+  try {
+    // Simple query
+    const result = await db.query('SELECT NOW() as current_time');
+    console.log('Current time:', result.rows[0].current_time);
+
+    // Parameterized query
+    const users = await db.query(
+      'SELECT * FROM users WHERE active = $1 LIMIT $2',
+      [true, 10]
+    );
+    console.log('Active users:', users.rows);
+
+    // Transaction example
+    await db.transaction(async (client) => {
+      await client.query('INSERT INTO logs (message) VALUES ($1)', ['Transaction started']);
+      await client.query('INSERT INTO logs (message) VALUES ($1)', ['Transaction completed']);
+    });
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    // Always disconnect
+    await db.disconnect();
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@entergreat/pg-light",
+  "description": "Lightweight PostgreSQL client with Mongoose-like models. One-line connection, friendly CRUD API, and raw SQL support.",
+  "version": "1.0.0",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nivkman/pg-light.git"
+  },
+  "keywords": [
+    "postgresql",
+    "postgres",
+    "pg",
+    "database",
+    "connection",
+    "pool",
+    "lightweight",
+    "simple",
+    "one-liner",
+    "sql",
+    "query",
+    "node",
+    "nodejs",
+    "model",
+    "mongoose",
+    "orm",
+    "crud",
+    "activerecord"
+  ],
+  "author": "EnterGreat",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/nivkman/pg-light/issues"
+  },
+  "homepage": "https://github.com/nivkman/pg-light#readme",
+  "dependencies": {
+    "pg": "^8.11.3",
+    "knex": "^3.1.0",
+    "logger-standard": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,117 @@
+import pg from 'pg';
+import knex from 'knex';
+import { Logger } from 'logger-standard';
+import { Model } from './model.js';
+
+const { Pool } = pg;
+
+function isConnectionString(config) {
+  return typeof config === 'string';
+}
+
+function createPoolConfig(config) {
+  if (isConnectionString(config)) {
+    return { connectionString: config };
+  }
+  return config;
+}
+
+function createLogger(options) {
+  const service = options?.service || 'pg-light';
+  const logLevel = options?.logLevel || 'info';
+  return new Logger({ service, logLevel });
+}
+
+function createKnexInstance(config) {
+  const connection = isConnectionString(config) ? config : createPoolConfig(config);
+  return knex({ client: 'pg', connection });
+}
+
+class PgLight {
+  #pool = null;
+  #logger = null;
+  #knex = null;
+  _logger = null;
+
+  constructor(pool, logger, knexInstance) {
+    this.#pool = pool;
+    this.#logger = logger;
+    this.#knex = knexInstance;
+    this._logger = logger;
+  }
+
+  async query(text, params = []) {
+    this.#logger.debug(`Executing query: ${text}`);
+    const result = await this.#pool.query(text, params);
+    this.#logger.debug(`Query returned ${result.rowCount} rows`);
+    return result;
+  }
+
+  async #executeTransaction(client, callback) {
+    await client.query('BEGIN');
+    await callback(client);
+    await client.query('COMMIT');
+    this.#logger.debug('Transaction committed');
+  }
+
+  async #rollbackTransaction(client, error) {
+    await client.query('ROLLBACK');
+    this.#logger.error(`Transaction rolled back: ${error.message}`);
+    throw error;
+  }
+
+  async transaction(callback) {
+    const client = await this.#pool.connect();
+    try {
+      await this.#executeTransaction(client, callback);
+    } catch (error) {
+      await this.#rollbackTransaction(client, error);
+    } finally {
+      client.release();
+    }
+  }
+
+  async disconnect() {
+    await this.#pool.end();
+    await this.#knex.destroy();
+    this.#logger.info('Database connection closed');
+  }
+
+  getPool() {
+    return this.#pool;
+  }
+
+  model(tableName) {
+    return new Model(this, tableName);
+  }
+
+  builder(tableName) {
+    this.#logger.debug(`Creating query builder for ${tableName}`);
+    return this.#knex(tableName);
+  }
+
+  get knex() {
+    return this.#knex;
+  }
+}
+
+async function testConnection(pool, logger) {
+  try {
+    await pool.query('SELECT NOW()');
+    logger.info('Database connected successfully');
+  } catch (error) {
+    logger.error(`Connection failed: ${error.message}`);
+    throw error;
+  }
+}
+
+export async function connectDB(config, options = {}) {
+  const logger = createLogger(options);
+  const poolConfig = createPoolConfig(config);
+  const pool = new Pool(poolConfig);
+  const knexInstance = createKnexInstance(config);
+  await testConnection(pool, logger);
+  return new PgLight(pool, logger, knexInstance);
+}
+
+export { Model };

package/src/model.js

@@ -0,0 +1,137 @@
+function buildWhereClause(conditions) {
+  const keys = Object.keys(conditions);
+  const whereParts = keys.map((key, idx) => `${key} = $${idx + 1}`);
+  const values = keys.map(key => conditions[key]);
+  return { clause: whereParts.join(' AND '), values };
+}
+
+function createPlaceholders(keys) {
+  return keys.map((_, idx) => `$${idx + 1}`).join(', ');
+}
+
+function getKeysAndValues(data) {
+  const keys = Object.keys(data);
+  const values = keys.map(key => data[key]);
+  return { keys, values };
+}
+
+function buildInsertQuery(tableName, data) {
+  const { keys, values } = getKeysAndValues(data);
+  const columns = keys.join(', ');
+  const placeholders = createPlaceholders(keys);
+  const text = `INSERT INTO ${tableName} (${columns}) VALUES (${placeholders}) RETURNING *`;
+  return { text, values };
+}
+
+function buildSetClause(data) {
+  const keys = Object.keys(data);
+  const setParts = keys.map((key, idx) => `${key} = $${idx + 1}`);
+  const values = keys.map(key => data[key]);
+  return { clause: setParts.join(', '), values };
+}
+
+function buildUpdateQuery(tableName, data, conditions) {
+  const { clause: setClause, values: setValues } = buildSetClause(data);
+  const { clause: whereClause, values: whereValues } = buildWhereClause(conditions);
+  const text = `UPDATE ${tableName} SET ${setClause} WHERE ${whereClause} RETURNING *`;
+  const values = [...setValues, ...whereValues];
+  return { text, values };
+}
+
+export class Model {
+  #db = null;
+  #tableName = null;
+  #logger = null;
+
+  constructor(db, tableName) {
+    this.#db = db;
+    this.#tableName = tableName;
+    this.#logger = db._logger;
+  }
+
+  async find(conditions = {}, options = {}) {
+    const hasConditions = Object.keys(conditions).length > 0;
+
+    if (!hasConditions) {
+      return this.#findAll(options);
+    }
+
+    return this.#findWithConditions(conditions, options);
+  }
+
+  async #findAll(options) {
+    const limit = options.limit ? `LIMIT ${options.limit}` : '';
+    const offset = options.offset ? `OFFSET ${options.offset}` : '';
+    const query = `SELECT * FROM ${this.#tableName} ${limit} ${offset}`.trim();
+    const result = await this.#db.query(query);
+    return result.rows;
+  }
+
+  async #findWithConditions(conditions, options) {
+    const { clause, values } = buildWhereClause(conditions);
+    const limit = options.limit ? `LIMIT ${options.limit}` : '';
+    const offset = options.offset ? `OFFSET ${options.offset}` : '';
+    const query = `SELECT * FROM ${this.#tableName} WHERE ${clause} ${limit} ${offset}`.trim();
+    const result = await this.#db.query(query, values);
+    return result.rows;
+  }
+
+  async findOne(conditions) {
+    const rows = await this.find(conditions, { limit: 1 });
+    return rows[0] || null;
+  }
+
+  async findById(id) {
+    return this.findOne({ id });
+  }
+
+  async create(data) {
+    const { text, values } = buildInsertQuery(this.#tableName, data);
+    const result = await this.#db.query(text, values);
+    this.#logger.debug(`Created record in ${this.#tableName}`);
+    return result.rows[0];
+  }
+
+  async update(conditions, data) {
+    const { text, values } = buildUpdateQuery(this.#tableName, data, conditions);
+    const result = await this.#db.query(text, values);
+    this.#logger.debug(`Updated ${result.rowCount} rows in ${this.#tableName}`);
+    return result.rows;
+  }
+
+  async updateById(id, data) {
+    const result = await this.update({ id }, data);
+    return result[0] || null;
+  }
+
+  async delete(conditions) {
+    const { clause, values } = buildWhereClause(conditions);
+    const query = `DELETE FROM ${this.#tableName} WHERE ${clause} RETURNING *`;
+    const result = await this.#db.query(query, values);
+    this.#logger.debug(`Deleted ${result.rowCount} rows from ${this.#tableName}`);
+    return result.rows;
+  }
+
+  async deleteById(id) {
+    const result = await this.delete({ id });
+    return result[0] || null;
+  }
+
+  async #countAll() {
+    const result = await this.#db.query(`SELECT COUNT(*) FROM ${this.#tableName}`);
+    return parseInt(result.rows[0].count);
+  }
+
+  async #countWithConditions(conditions) {
+    const { clause, values } = buildWhereClause(conditions);
+    const query = `SELECT COUNT(*) FROM ${this.#tableName} WHERE ${clause}`;
+    const result = await this.#db.query(query, values);
+    return parseInt(result.rows[0].count);
+  }
+
+  async count(conditions = {}) {
+    const hasConditions = Object.keys(conditions).length > 0;
+    if (!hasConditions) return this.#countAll();
+    return this.#countWithConditions(conditions);
+  }
+}