@aceitadev/adatabase 0.3.0 → 0.3.6

package/README.md

@@ -1,66 +1,171 @@
-```markdown
-# aMySQL - Node.js (TypeScript) port
-
-Esta é uma implementação inicial do seu sistema aMySQL para Node.js usando TypeScript e decorators.
-
-Principais características
-- Pool de conexões (mysql2/promise)
-- Decorators: @Table, @Column, @Id, @Nullable
-- ColumnAdapter para tipos serializados customizados
-- ActiveRecord com save/update/delete
-- QueryBuilder (where/order/limit)
-- SchemaManager para criar/atualizar colunas automaticamente
-
-Como usar (exemplo rápido)
-
-1) Instale dependências
-npm install
-
-2) Configure tsconfig (já incluído) e habilite experimentalDecorators e emitDecoratorMetadata.
-
-3) Exemplo de modelo (src/example.ts)
-```ts
-import "reflect-metadata";
-import { init } from "./MySQL";
-import { Table } from "./decorators/Table";
-import { Column } from "./decorators/Column";
-import { Id } from "./decorators/Id";
-import { ActiveRecord } from "./ActiveRecord";
-import { SchemaManager } from "./SchemaManager";
-
-@Table("users")
-class User extends ActiveRecord {
-  @Id()
-  id!: number;
-
-  @Column({ limit: 150 })
-  name!: string;
-
-  @Column()
-  email!: string;
-}
-
-async function main() {
-  await init({ host: "127.0.0.1", database: "test", user: "root", password: "" });
-  const sm = new SchemaManager([User]);
-  await sm.migrate();
-
-  const u = new User();
-  u.name = "Fulano";
-  u.email = "fulano@example.com";
-  await u.save();
-
-  const fetched = await User.find().where("email", "=", "fulano@example.com").first();
-  console.log(fetched);
-}
-
-main().catch(console.error);
-```
-
-Limitações & próximos passos
-- QueryBuilder suporta nomes de campos como strings; não foi implementado introspecção de lambda getter como no Java.
-- Adapters: você fornece uma classe com métodos serialize/deserialize para o Column decorator.
-- Migração: apenas cria tabelas e adiciona colunas que faltam; não altera ou remove colunas existentes.
-- Recomendado: adicionar testes, melhorar mapeamento de tipos (enums, UUID), e adicionar caching e transações.
-
-```
+# aDatabase ORM
+
+aDatabase is a lightweight and easy-to-use ORM (Object-Relational Mapping) for TypeScript, inspired by the Active Record pattern. It allows you to interact with your database using object-oriented syntax, abstracting away the need to write raw SQL queries for most common operations.
+
+## Features
+
+*   **Active Record Pattern**: Models represent database tables and instances represent rows.
+*   **Decorator-based Schema**: Define your database schema using simple decorators.
+*   **Multi-database Support**: Supports both MySQL and PostgreSQL.
+*   **Query Builder**: A fluent API for building complex queries.
+*   **Schema Migration**: Keep your database schema in sync with your models.
+*   **Relationships**: Supports `HasOne`, `HasMany`, and `BelongsTo` relationships.
+
+## Installation
+
+```bash
+npm install @aceitadev/adatabase
+```
+
+## Configuration
+
+First, you need to initialize the database connection. This should be done once when your application starts.
+
+```typescript
+import { init } from '@aceitadev/adatabase';
+
+init('mysql', {
+  host: 'localhost',
+  user: 'root',
+  password: 'password',
+  database: 'my_database'
+});
+```
+
+Supported database types are `'mysql'` and `'postgres'`.
+
+## Defining Models
+
+Models are defined as classes that extend `ActiveRecord`. You use decorators to map the class and its properties to a database table and its columns.
+
+```typescript
+import { ActiveRecord, Table, Id, Column } from '@aceitadev/adatabase';
+
+@Table('users')
+export class User extends ActiveRecord {
+  @Id()
+  id: number;
+
+  @Column({ type: String })
+  name: string;
+
+  @Column({ type: String, unique: true })
+  email: string;
+}
+```
+
+## CRUD Operations
+
+### Creating and Saving Records
+
+To create a new record, instantiate a model and call the `save()` method.
+
+```typescript
+const user = new User();
+user.name = 'John Doe';
+user.email = 'john.doe@example.com';
+await user.save();
+```
+
+### Finding Records
+
+Use the static `find()` method to get a `QueryBuilder` instance.
+
+**Find all users:**
+
+```typescript
+const users = await User.find().get();
+```
+
+**Find a single user by ID:**
+
+```typescript
+const user = await User.find().where('id', '=', 1).first();
+```
+
+**Find users with a specific condition:**
+
+```typescript
+const users = await User.find().where('name', 'LIKE', 'John%').get();
+```
+
+### Updating Records
+
+To update a record, modify its properties and call `save()` again.
+
+```typescript
+const user = await User.find().where('id', '=', 1).first();
+if (user) {
+  user.name = 'Jane Doe';
+  await user.save();
+}
+```
+
+### Deleting Records
+
+To delete a record, call the `delete()` method on a model instance.
+
+```typescript
+const user = await User.find().where('id', '=', 1).first();
+if (user) {
+  await user.delete();
+}
+```
+
+## Relationships
+
+You can define relationships between your models using the `@BelongsTo`, `@HasMany`, and `@HasOne` decorators.
+
+```typescript
+import { ActiveRecord, Table, Id, Column, BelongsTo, HasMany } from '@aceitadev/adatabase';
+
+@Table('posts')
+export class Post extends ActiveRecord {
+  @Id()
+  id: number;
+
+  @Column({ type: String })
+  title: string;
+
+  @Column({ type: Number })
+  userId: number;
+
+  @BelongsTo(() => User, { foreignKey: 'userId' })
+  user: User;
+}
+
+@Table('users')
+export class User extends ActiveRecord {
+  @Id()
+  id: number;
+
+  @Column({ type: String })
+  name: string;
+
+  @HasMany(() => Post, { foreignKey: 'userId' })
+  posts: Post[];
+}
+```
+
+To eager-load relationships, use the `include()` method in the `QueryBuilder`.
+
+```typescript
+const userWithPosts = await User.find().where('id', '=', 1).include(Post).first();
+console.log(userWithPosts.posts);
+```
+
+## Schema Migration
+
+The `SchemaManager` helps you keep your database schema in sync with your models.
+
+```typescript
+import { SchemaManager } from '@aceitadev/adatabase';
+import { User, Post } from './models'; // Import your models
+
+const schemaManager = new SchemaManager([User, Post]);
+await schemaManager.migrate();
+```
+
+When you run `migrate()`, the `SchemaManager` will:
+*   Create tables that don't exist.
+*   Add columns that are missing from existing tables.

package/dist/QueryBuilder.d.ts

@@ -16,6 +16,7 @@ export declare class QueryBuilder<T extends ActiveRecord> {
     limit(count: number): this;
     offset(count: number): this;
     first(): Promise<T | null>;
+    count(): Promise<number>;
     get(): Promise<T[]>;
     private getColumnName;
     private mapRowsToEntities;

package/dist/QueryBuilder.js

@@ -63,6 +63,47 @@ class QueryBuilder {
             return rows.length > 0 ? rows[0] : null;
         });
     }
+    count() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const table = (0, Table_1.getTableName)(this.model);
+            if (!table) {
+                throw new PersistenceException_1.PersistenceException("Model has no @Table", null);
+            }
+            const columnsMeta = (0, Column_1.getColumnMeta)(this.model);
+            if (!columnsMeta) {
+                throw new PersistenceException_1.PersistenceException("Model has no @Column decorators", null);
+            }
+            const allowedOperators = ['=', '!=', '<>', '>', '<', '>=', '<=', 'LIKE', 'IN', 'IS NULL', 'IS NOT NULL'];
+            const params = [];
+            const baseAlias = 't1';
+            let sql = `SELECT COUNT(*) as count FROM \`${table}\` AS ${baseAlias}`;
+            if (this.whereClauses.length > 0) {
+                sql += " WHERE ";
+                this.whereClauses.forEach((c, i) => {
+                    if (!allowedOperators.includes(c.operator.toUpperCase())) {
+                        throw new Error(`Invalid operator used: ${c.operator}`);
+                    }
+                    if (i > 0) {
+                        sql += ` ${c.booleanOp} `;
+                    }
+                    const colName = this.getColumnName(c.field, columnsMeta);
+                    sql += `\`${baseAlias}\`.\`${colName}\` ${c.operator} ?`;
+                    params.push(c.value);
+                });
+            }
+            try {
+                const rows = yield (0, Database_1.query)(sql, params);
+                if (rows && rows.length > 0 && rows[0].count !== undefined) {
+                    return Number(rows[0].count);
+                }
+                return 0;
+            }
+            catch (error) {
+                console.error("Failed to execute count query:", error);
+                throw new PersistenceException_1.PersistenceException("Failed to count records");
+            }
+        });
+    }
     get() {
         return __awaiter(this, void 0, void 0, function* () {
             const table = (0, Table_1.getTableName)(this.model);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@aceitadev/adatabase",
-    "version": "0.3.0",
+    "version": "0.3.6",
     "description": "Uma biblioteca para facilitar a interação com bancos de dados MySQL e PostgreSQL em projetos TypeScript/Node.js.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",