tspace-mysql 1.4.8 → 1.5.0

package/README.md

@@ -3,8 +3,7 @@
 [![NPM version](https://img.shields.io/npm/v/tspace-mysql.svg)](https://www.npmjs.com)
 [![NPM downloads](https://img.shields.io/npm/dm/tspace-mysql.svg)](https://www.npmjs.com)
 
-tspace-mysql is an ORM that can run in NodeJs and can be used with TypeScript. 
-Its always support the latest TypeScript and JavaScript features and provide additional features that help you to develop.
+tspace-mysql is an Object-Relational Mapping (ORM) tool designed to run seamlessly in Node.js and is fully compatible with TypeScript. It consistently supports the latest features in both TypeScript and JavaScript, providing additional functionalities to enhance your development experience.
 
 ## Install
 
@@ -19,6 +18,7 @@ npm install tspace-mysql --save
 - [Database Transactions](#database-transactions)
 - [Connection](#connection)
 - [Backup](#backup)
+- [Injection](#injection)
 - [Generating Model Classes](#generating-model-classes)
 - [Model Conventions](#model-conventions)
   - [Relationships](#relationships)
@@ -29,6 +29,7 @@ npm install tspace-mysql --save
     - [Deeply Nested Relations](#deeply-nested-relations)
     - [Relation Exists](#relation-exists)
     - [Built in Relation Functions](#built-in-relation-functions)
+    - [Decorator](#decorator)
   - [Schema Model](#schema-model)
     - [Validation](#validation)
     - [Sync](#sync)
@@ -43,7 +44,7 @@ npm install tspace-mysql --save
 - [Blueprint](#blueprint)
 
 ## Configuration
-Created your environment variables is to use a '.env' file, you may establish a connection is this:
+To establish a connection, the recommended method for creating your environment variables is by using a '.env' file. using the following:
 ```js
 DB_HOST     = localhost
 DB_PORT     = 3306
@@ -59,7 +60,7 @@ DB_DATABASE = database
  *  DB_DATE_STRINGS     = true
 */
 ```
-Or you can created file name 'db.tspace' to use a connection  this:
+You can also create a file named 'db.tspace' to configure the connection. using the following:
 ```js
 source db {
     host               = localhost
@@ -77,7 +78,7 @@ source db {
 
 ```
 ## Running Queries
-Once you have configured your database connection, you may run queries is this :
+Once you have configured your database connection, you can execute queries using the following:
 ```js
 +-------------+--------------+----------------------------+
 |                     table users                         |
@@ -100,50 +101,78 @@ Once you have configured your database connection, you may run queries is this :
 
 import { DB } from 'tspace-mysql'
 (async () => {
-    await new DB('users').findMany() //  SELECT * FROM users => Array
-    await new DB('users').findOne()  //  SELECT * FROM users LIMIT 1 => Object
+    await new DB('users').findMany() 
+    //  SELECT * FROM users => Array
+    await new DB('users').findOne()  
+    //  SELECT * FROM users LIMIT 1 => Object
 })()
 
 ```
 Running A Raw Query
 ```js
-const rawQuery = await new DB().query('SELECT * FROM users') 
+const rawQuery = await new DB().query('SELECT * FROM users')  
+// SELECT * FROM users;
 
 ```
 Running A Select Query
 ```js
 const select = await new DB('users').select('id','username').findOne() 
+// SELECT `users`.`id`, `users`.`username` FROM `users` LIMIT 1;
 
 const selectRaw = await new DB('users').selectRaw('COUNT(id)').findMany()
+// SELECT COUNT(id) FROM `users`;
 
 const selectObject = await new DB('posts')
 .join('posts.user_id', 'users.id')
 .select('posts.*')
-.selectObject({ id : 'users.id', name : 'users.name' , email : 'users.email'},'user')
+.selectObject({ id : 'users.id', name : 'users.name' , email : 'users.email'} , 'user')
 .findOne()
 
+// SELECT posts.*, JSON_OBJECT('id' , `users`.`id` , 'name' , `users`.`name` , 'email' , `users`.`email`) AS `user` 
+// FROM `posts` INNER JOIN `users` ON `posts`.`user_id` = `users`.`id` LIMIT 1;
+
 /**
  * @example except
  */
-await new DB('users').except('id','username').findOne() 
+await new DB('users').except('id').findOne()
+// SELECT `users`.`email`, `users`.`username` FROM `users` LIMIT 1; 
 ```
 
 Running A OrderBy & GroupBy Query
 ```js
 await new DB('users').orderBy('id','asc').findOne()
+// SELECT * FROM `users` ORDER BY `id` ASC LIMIT 1;
+
 await new DB('users').orderBy('id','desc').findOne()
+// SELECT * FROM `users` ORDER BY `id` DESC LIMIT 1;
+
 await new DB('users').oldest('id').findOne()
+// SELECT * FROM `users` ORDER BY `id` ASC LIMIT 1;
+
 await new DB('users').latest('id').findOne()
+// SELECT * FROM `users` ORDER BY `id` DESC LIMIT 1;
 
 await new DB('users').groupBy('id').findOne()
-await new DB('users').groupBy('id','usernamename').findOne()
+// SELECT * FROM `users` GROUP BY `id` LIMIT 1;
+
+await new DB('users').groupBy('id','username').findOne()
+// SELECT * FROM `users` GROUP BY `id`, `username` LIMIT 1;
+
+await new DB('users').orderBy('id').groupBy('id','username').findOne()
+// SELECT * FROM `users` GROUP BY `id`, `username` ORDER BY `id` ASC LIMIT 1;
+
 ```
 
 Running A Join Query
 ```js
 await new DB('posts').join('posts.user_id' , 'users.id').findMany()
+// SELECT * FROM `posts` INNER JOIN `users` ON `posts`.`user_id` = `users`.`id`;
+
 await new DB('posts').leftJoin('posts.user_id' , 'users.id').findMany()
+// SELECT * FROM `posts` LEFT JOIN `users` ON `posts`.`user_id` = `users`.`id`;
+
 await new DB('posts').rightJoin('posts.user_id' , 'users.id').findMany()
+// SELECT * FROM `posts` RIGHT JOIN `users` ON `posts`.`user_id` = `users`.`id`;
 ```
 
 Running A Where Query
@@ -162,7 +191,7 @@ const whereBetween = await new DB('users').whereBetween('id',[1,2]).findMany()
 
 const whereSubQuery = await new DB('users').whereSubQuery('id','SELECT id FROM users').findMany()
 // SELECT * FROM `users` WHERE `users`.`id` IN (SELECT id FROM users);
-// or use -> await new DB('users').whereSubQuery('id',new DB('users').select('id').toString()).findMany()
+// also you can use -> await new DB('users').whereSubQuery('id',new DB('users').select('id').toString()).findMany()
 
 const whereNull = await new DB('users').whereNull('username').findOne()
 // SELECT * FROM `users` WHERE `users`.`username` IS NULL LIMIT 1;
@@ -189,7 +218,21 @@ const whereWhenIsFalse = await new DB('users').where('id',1).when(false, (query)
 Running A Hook Query
 ```js
 const hookResult = (result) => console.log('hook!! result => ',result)
-const user = await new DB('users').where('id',1).hook(hookResult).findOne()
+const user = await new DB('users').where('id',1).hook(hookResult).findMany()
+```
+
+Running A Faker
+```js
+
+await new DB('users').faker(10)
+
+// custom faker 
+await new DB('users').faker(10 , (row , index) => {
+    return {
+        ...row,
+        custom : 'custom' + index
+    }
+})
 ```
 
 Running A Insert Query
@@ -200,19 +243,9 @@ const user = await new DB('users')
     email : 'tspace3@gmail.com'
 })
 .save()
-// user =>  { id : 3 , username : 'tspace3', email : 'tspace3@gmail.com'}
+// INSERT INTO `users` (`name`,`email`) VALUES ('tspace3','tspace3@gmail.com');
 
 +--------------------------------------------------------------------------+
-
-const reposity = new DB('users')
-reposity.name = 'tspace4'
-reposity.email = 'tspace4@gmail.com'
-
-await reposity.save()
-
-const { result } = reposity
-// result =>  { id : 4 , username : 'tspace4', email : 'tspace4@gmail.com'}
-
 const users = await new DB('users')
 .createMultiple([
     {
@@ -230,6 +263,8 @@ const users = await new DB('users')
 ])
 .save()
 
+// INSERT INTO `users` (`name`,`email`) VALUES ('tspace4','tspace4@gmail.com'),('tspace5','tspace5@gmail.com'),('tspace6','tspace6@gmail.com');
+
 const users = await new DB('users')
 .where('name','tspace4')
 .where('email','tspace4@gmail.com')
@@ -238,7 +273,10 @@ const users = await new DB('users')
     email : 'tspace4@gmail.com'
 })
 .save()
-// if has exists return null, if not exists created new data
+// if exists return null, if not exists created new data
+// SELECT EXISTS(SELECT 1 FROM `users` WHERE `users`.`name` = 'tspace4' AND `users`.`email` = 'tspace4@gmail.com' LIMIT 1) AS 'exists';
+// INSERT INTO `users` (`name`,`email`) VALUES ('tspace4','tspace4@gmail.com');
+
 
 const users = await new DB('users')
 .where('name','tspace4')
@@ -249,6 +287,9 @@ const users = await new DB('users')
 })
 .save()
 // if has exists return data, if not exists created new data
+// SELECT EXISTS(SELECT 1 FROM `users` WHERE `users`.`name` = 'tspace4' AND `users`.`email` = 'tspace4@gmail.com' LIMIT 1) AS 'exists';
+// SELECT * FROM `users` WHERE `users`.`name` = 'tspace4' AND `users`.`email` = 'tspace4@gmail.com';
+// INSERT INTO `users` (`name`,`email`) VALUES ('tspace4','tspace4@gmail.com');
 
 ```
 Running A Update Query
@@ -271,18 +312,6 @@ const user = await new DB('users')
 .save()
 // UPDATE `users` SET `name` = CASE WHEN (`name` = "" OR `name` IS NULL) THEN "tspace1**" ELSE `name` END,`email` = 'tspace1@gmail.com' WHERE `users`.`id` = '1' LIMIT 1;
 
-
-+--------------------------------------------------------------------------+
-
-const reposity = new DB('users').where('id',1)
-reposity.name = 'tspace1++'
-reposity.email = 'tspace1++@gmail.com'
-
-await reposity.save()
-// UPDATE `users` SET `name` = 'tspace1**',`email` = 'tspace1@gmail.com' WHERE `users`.`id` = '1' LIMIT 1;
-const { result } = reposity
-// result =>  { id : 1 , username : 'tspace1++', email : 'tspace1++@gmail.com'} 
-
 ```
 Running A Update Or Created Query
 ```js
@@ -304,7 +333,7 @@ const deleted = await new DB('users').where('id',1).delete()
 ``` 
 ## Database Transactions 
 
-Within a Database Transaction, you may use the:
+Within a database transaction, you can utilize the following:
 
 ```js
 const connection = await new DB().beginTransaction()
@@ -317,17 +346,17 @@ try {
     await connection.startTransaction()
 
     const user = await new User()
-        .create({
-            name : `tspace`,
-            email : 'tspace@example.com'
-        })
-        /**
-         *
-         * bind method for make sure this connection has same transaction in connection
-         * @params {Function} connection 
-         */
-        .bind(connection)
-        .save()
+    .create({
+        name : `tspace`,
+        email : 'tspace@example.com'
+    })
+    /**
+     *
+     * bind method for make sure this connection has same transaction in connection
+     * @params {Function} connection 
+     */
+    .bind(connection)
+    .save()
 
     const posts = await new Post()
     .createMultiple([
@@ -364,7 +393,7 @@ try {
 
 ```
 ## Connection
-When establishing a connection, you may establish options is this:
+When establishing a connection, you can specify options as follows:
 ```js
 const connection = await new DB().getConnection({
     host: 'localhost',
@@ -375,24 +404,23 @@ const connection = await new DB().getConnection({
 })
 
 const users = await new DB('users')
-.bind(connection)
+.bind(connection) // don't forget this
 .findMany()
-// users => [{ .... }]
 ```
 
 ## Backup
-Backup database, you may backup is this:
+To backup a database, you can perform the following steps:
 ```js
 /**
  * 
- * @param conection defalut current connection
+ * @param {string} database Database selected
+ * @param {object | null} to defalut new current connection
  */
 const backup = await new DB().backup({
-     database: 'try-to-backup',  // clone current database to this database
-     connection ?: {
+    database: 'try-to-backup',  // clone current database to this database
+    to ?: {
         host: 'localhost',
         port : 3306,
-        database: 'database'
         username: 'username',
         password: 'password',
     }
@@ -415,11 +443,32 @@ const backupToFile = await new DB().backupToFile({
     }
 })
 // backupToFile => backup.sql
+
+/**
+ * 
+ * @param {string} database new db name
+ */
+await new DB().cloneDB('try-to-clone')
+
+```
+
+## Injection
+The 'tspace-mysql' library is configured to automatically escape SQL injection by default.
+Let's example a escape SQL injection and XSs injection:
+```js
+const input = "admin' OR '1'='1"
+DB.escape(input)
+// admin OR 1=1
+
+//XSS
+const input = "text hello!<script>alert('XSS attack');</script>"
+DB.escapeXSS(input)
+// text hello!
+
 ```
 
 ## Generating Model Classes
-To get started, let's install npm install tspace-mysql -g  
-you may use the make:model command to generate a new model:
+To get started, install the 'tspace-mysql' package globally using the following npm command:
 
 ```js
 /**
@@ -435,14 +484,41 @@ npm install tspace-mysql -g
 tspace-mysql make:model <model name> --dir=< directory >
 
 # tspace-mysql make:model User --dir=App/Models 
-# => App/Models/User.ts
+# App/Models/User.ts
 ```
 ## Model Conventions
 Models generated by the make:model command will be placed in the specific directory. 
-Let's examine a basic model class:
+Let's example a basic model class:
 
 ```js
 import { Model } from 'tspace-mysql'
+// If you want to specify a global setting for the 'Model'
+Model.global({
+  uuid: true,
+  softDelete: true,
+  timestamp: true
+})
+
+/**
+class Observe {
+
+  public selected(results : unknown) {
+    console.log({ results , selected : true })
+  }
+
+  public created(results : unknown) {
+      console.log({ results , created : true })
+  }
+
+  public updated(results : unknown) {
+    console.log({ results , updated : true })
+  }
+
+  public deleted(results : unknown) {
+    console.log({ results , deleted : true })
+  }
+}
+*/
 class User extends Model {
   constructor(){
     super()
@@ -466,6 +542,7 @@ class User extends Model {
      * this.useLoadRelationsInRegistry() // => auto generated result from relationship to results
      * this.useBuiltInRelationFunctions() // => build-in functions relationships to results
      * this.useHooks([(r) => console.log(r)])
+     * this.useObserver(Observe)
      * this.useSchema ({ 
      *     id          : new Blueprint().int().notNull().primary().autoIncrement(),
      *     uuid        : new Blueprint().varchar(50).null(),
@@ -512,8 +589,8 @@ export { User }
 export default User
 ```
 ## Relationships
-Relationships are defined as methods on your Model classes
-Let's examine a basic relations :
+Relationships are defined as methods on your Model classes. 
+Let's example a basic relationship:
 
 ## One To One
 A one-to-one relationship is used to define relationships where a single model is the parent to one child models
@@ -659,8 +736,8 @@ const userUsingFunction = await new User().roles().findOne()
 ```
 
 ## Deeply Nested Relations
-Relationships can deeply relations. 
-let's example a deep in relations :
+Relationships can involve deep connections. 
+Let's example of a deep relationship:
 ```js
 import { Model } from 'tspace-mysql'
 
@@ -735,8 +812,8 @@ await new User()
 
 ```
 ## Relation Exists
-Relationships can return only result is not empty in relations (soft delete). 
-let's example a exists in relations :
+Relationships can return results only if they are not empty in relations, considering soft deletes. 
+Let's illustrate this with an example of an existence check in relations:
 ```js
 +-------------+--------------+----------------------------+--------------------+
 |                     table users                         |                    |
@@ -832,8 +909,7 @@ await new User().relationsExists('posts').findMany()
 
 ```
 ## Built in Relation Functions
-Relationships can using built in function in results 
-let's example a built in function :
+Certainly, let's illustrate the use of a built-in function in the results of relationships:
 ```js
 import { Model } from 'tspace-mysql'
 
@@ -871,16 +947,109 @@ for (const post of posts) {
     const comments = await post.$comments()
 }
 
+```
+
+## Decorator
+Decorators can be used in a Model.
+Let's illustrate this with an example of a decorators:
+```js
+
+import { 
+    Blueprint, Model , 
+    Table ,TableSingular, TablePlural, 
+    UUID, SoftDelete, Timestamp,
+    Pattern, CamelCase , snakeCase ,
+    Column, Validate, Observer,
+    HasMany, HasOne, BelongsTo, BelongsToMany
+    
+} from 'tspace-mysql'
+import { Post } from './Post'
+import { PostUser } from './PostUser'
+
+class UserObserve {
+
+    public selected(results : any) {
+      console.log({ results , selected : true })
+    }
+  
+    public created(results : unknown) {
+        console.log({ results , created : true })
+    }
+  
+    public updated(results : unknown) {
+      console.log({ results , updated : true })
+    }
+  
+    public deleted(results : unknown) {
+      console.log({ results , deleted : true })
+    }
+  }
+
+@Pattern('camelCase')
+@Observer(UserObserve)
+@UUID()
+@SoftDelete()
+@Timestamp()
+@Table('users')
+class User extends Model {
+
+    @Column(() => new Blueprint().int().notNull().primary().autoIncrement())
+    public id!: number
+
+    @Column(() => new Blueprint().varchar(50).null())
+    public uuid!: string
+
+    @Column(() => new Blueprint().varchar(50).null())
+    @Validate({
+        type : String,
+        require : true,
+        length : 50,
+        match: /^[a-zA-Z0-9._]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
+        unique : true,
+        fn : (email : string) => /^[a-zA-Z0-9._]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(email)
+    })
+    public email!: string
+
+    @Column(() => new Blueprint().varchar(50).null())
+    public name !: string
+
+    @Column(() => new Blueprint().varchar(50).null())
+    public username !: string
+
+    @Column(() => new Blueprint().varchar(50).null())
+    public password !: string
+
+    @Column(() => new Blueprint().timestamp().null())
+    public createdAt!: Date
+
+    @Column(() => new Blueprint().timestamp().null())
+    public updatedAt!: Date
+
+    @Column(() => new Blueprint().timestamp().null())
+    public deletedAt!: Date
+ 
+    @HasMany({ model : Post })
+    public posts!: Post[]
+
+    @HasOne({ model : Post })
+    public post!: Post
+
+    @BelongsToMany({ model : Post , modelPivot : PostUser })
+    public users!: PostUser[]
+}
+
+export { User }
+export default User
+
 ```
 ## Schema Model
-Define the schema of Model 
-let's example a validator model:
+Define the schema of a Model
 
 ## Validation
 Validate the schema of Model 
 let's example a validator model:
 ```js
-
+import { Model , Blueprint , Column } from 'tspace-mysql'
 class User extends Model {
   constructor(){
     super()
@@ -900,7 +1069,7 @@ class User extends Model {
       uuid :  Number,
       name : {
           type : String,
-          length : 191
+          length : 191,
           require : true,
           json : true
       },
@@ -910,7 +1079,7 @@ class User extends Model {
           length : 191,
           match: /^[a-zA-Z0-9._]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
           unique : true,
-          fn : (email : string) => !/^[a-zA-Z0-9._]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(email)
+          fn : (email : string) => /^[a-zA-Z0-9._]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(email)
       },
       createdAt : Date,
       updatedAt : Date,
@@ -978,6 +1147,9 @@ class Post extends Model {
 }
 await Schema.sync(`src/Models` , { force : true })
 
+// also you can sync by Model
+await new User().sync({ force : true })
+
 ```
 ## Query Builder
 Methods builder for queries
@@ -1003,7 +1175,6 @@ orWhereRaw(sql)
 orWhereIn(column , [])
 orWhereSubQuery(colmn , rawSQL)
 when(contition , callback)
-if(contition , callback)
 select(column1 ,column2 ,...N)
 distinct()
 selectRaw(column1 ,column2 ,...N)
@@ -1199,6 +1370,8 @@ Command will be generate models from table in database
 tspace-mysql generate:models --dir=<folder for creating> 
 or 
 tspace-mysql gen:models --dir=<folder for creating> --env=development
+or
+tspace-mysql generate:models --dir=app/Models --env=development --decorators
 
 ```