tspace-mysql 1.0.6 → 1.0.8

package/README.md

@@ -1,9 +1,10 @@
-# tspace-mysql
+## tspace-mysql
 
 [![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)
 
-Query builder object relation mapping
+TspaceMySQL is an ORM that can run in NodeJs and can be used with TypeScript. 
+Its goal is to always support the latest TypeScript and JavaScript features and provide additional features that help you to develop.
 
 ## Install
 
@@ -11,10 +12,29 @@ Install with [npm](https://www.npmjs.com/):
 
 ```sh
 npm install tspace-mysql --save
-
 ```
-## Setup
-.env
+## Basic Usage
+- [Configuration](#configuration)
+- [Running Queries](#running-queryies)
+- [Database Transactions](#database-transactions)
+- [Connection](#connection)
+- [Backup](#backup)
+- [Generating Model Classes](#generating-model-classes)
+- [Model Conventions](#model-conventions)
+- [Relationships](#relationships)
+  - [One To One](#one-to-one)
+  - [One To Many](#one-to-many)
+  - [One To One & One To Many (Inverse) / Belongs To](#inverse-belongs-to)
+  - [Many To Many](#many-to-many)
+- [Query Builder](#query-builder)
+- [Cli](#cli)
+  - [Make Model](#make-model)
+  - [Make Migration](#make-migration)
+  - [Migrate](#migrate)
+- [Blueprint](#blueprint)
+
+## Configuration
+Created your environment variables is to use a .env file, you may establish a connection is this:
 ```js
 DB_HOST = localhost
 DB_PORT = 3306
@@ -22,180 +42,341 @@ DB_USERNAME = root
 DB_PASSWORD = password
 DB_DATABASE = database
 ```
-## Getting Started
-queries data
+## Running Queries
+Once you have configured your database connection, you may run queries is this :
 ```js
++-------------+--------------+----------------------------+
+|                     table users                         |
++-------------+--------------+----------------------------+
+| id          | username     | email                      |
+|-------------|--------------|----------------------------|
+| 1           | tspace       | tspace@gmail.com           |
+| 2           | tspace2      | tspace2@gmail.com          |
++-------------+--------------+----------------------------+
+
 import { DB } from 'tspace-mysql'
 (async () => {
-    await new DB().raw('SELECT * FROM users')
-    await new DB().table('users').findMany()
-    await new DB().table('users').select('id').where('id',1).findOne()
-    await new DB().table('users').select('id').whereIn('id',[1,2,3]).findMany()
+    await new DB('users').findMany() // SELECT * FROM users => Array
+    await new DB('users').findOne() //  SELECT * FROM users LIMIT 1 => Object
 })()
 ```
-create data
-
+Running A Select Query
 ```js
-import { DB } from 'tspace-mysql'
-(async () => {
-    *ex pattern 1
-    const user = await new DB().table('users').create({
-          name : 'tspace',
-          email : 'tspace@gmail.com'
-      }).save()
-      
-      console.log(user)
-
-     *ex pattern 2
-     const u = new DB().table('users')
-         u.name = 'tspace'
-         u.email = 'tspace@gmail.com'
-         await u.save()
-      const { result : user } = u 
-      /* or const user = await u.save() */
-      console.log(user)
-})()  
+const selectQuery = await new DB('users').select('id','username').findOne() 
+    // selectQuery => { id : 1, username : 'tspace'}
+const selectQueries = await new DB('users').select('id','username').findMany() 
+    // selectQueries => [{ id : 1, username : 'tspace' } , { id : 2, username : 'tspace2'}]
+```
+Running A Where Query
+```js
+const user = await new DB('users').where('id',1).findOne()
+    // user => { id : 1 , username : 'tspace', email : 'tspace@gmail.com'}
+const users = await new DB('users').where('id','!=',1).findMany()
+    // users => [{ id : 2 , username : 'tspace2' , email : 'tspace2@gmail.com' }]
 ```
+Running A Insert Query
+```js
+const user = await new DB('users').create({
+        name : 'tspace3',
+        email : 'tspace3@gmail.com'
+    }).save()
+    // user =>  { id : 3 , username : 'tspace3', email : 'tspace3@gmail.com'}
+
++--------------------------------------------------------------------------+
 
-update data
+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'}
+```
+Running A Update Query
 ```js
-import { DB } from 'tspace-mysql'
-(async () => {
-     *ex pattern 1
-     const user = await new DB().table('users').update({
-          name : 'tspace',
-          email : 'tspace@gmail.com'
-      })
-      .where('id',1)
-      .save()
-      
-      console.log(user)
-
-    *ex pattern 2
-     const u = new DB().table('users').where('id',1)
-         u.name = 'tspace'
-         u.email = 'tspace@gmail.com'
-         await u.save()
-     const { result : user } = u 
-    /* or const user = await u.save() */
-     console.log(user)
-})()
+const user = await new DB('users').where('id',1)
+    .update({
+          name : 'tspace1**',
+          email : 'tspace1@gmail.com'
+    }).save()
+    // user =>  { id : 1 , username : 'tspace1**', email : 'tspace1@gmail.com'} 
+
++--------------------------------------------------------------------------+
+
+const reposity = new DB('users').where('id',1)
+    reposity.name = 'tspace1++'
+    reposity.email = 'tspace1++@gmail.com'
+    await reposity.save()
+const { result } = reposity
+    // result =>  { id : 1 , username : 'tspace1++', email : 'tspace1++@gmail.com'} 
 ```    
-delete data
+Running A Delete Query
 ```js
-import { DB } from 'tspace-mysql'
-(async () => {
-     await new User().where('id',1).delete()
-})()
+const deleted = await new DB('users').where('id',1).delete()
+    // deleted => true
 ``` 
+## Database Transactions 
+
+Within a database transaction, you may use the:
 
-## Transactions & Rollback
 ```js
-import { DB } from 'tspace-mysql'
-(async () => {
-   const transaction = await new DB().beginTransaction()
-   try {
-      const user = await new User().create({
-          name : 'tspace',
-          email : 'tspace@gmail.com'
-      })
-      .save(transaction)
-      
-       const posts = await new Post().createMultiple([
-            {   
-                user_id : user.id,
-                title : 'tspace post'
-            },
-            {   
-                user_id : user.id,
-                title : 'tspace post second'
-            }
-       ])
-      .save(transaction)
-      
-      throw new Error('try to transaction')
-      
-   } catch (err) {
-       const rollback = await transaction.rollback()
-       console.log(rollback ,'rollback !')
-   }
-})()
+const transaction = await new DB().beginTransaction()
+try {
+    const user = await new DB('users').create({
+        name : 'tspace5',
+        email : 'tspace5@gmail.com'
+    })
+   .save(transaction)
+    // user =>  { id : 5 , username : 'tspace5', email : 'tspace5@gmail.com'}
+  
+   const userSecond = await new DB('users').create({
+        name : 'tspace6',
+        email : 'tspace6@gmail.com'
+    })
+   .save(transaction)
+    // userSecond =>  { id : 6 , username : 'tspace6', email : 'tspace6@gmail.com'}
+   
+  throw new Error('try to using transaction')
+  
+} catch (err) {
+   const rollback = await transaction.rollback()
+   // rollback => true
+   // * rollback data user, userSecond in your database
+}
 ```
-     
-## Model Conventions
-basic model class and discuss some relations:
 
+## Connection
+When establishing a connection, you may establish options is this:
 ```js
-import { Model } from 'tspace-mysql'
-import Post from '../Post'
-import Comment from '../Comment'
-import User from '../User'
+const users = await new DB('users')
+    .connection({
+       host: 'localhost..',
+       port : 3306,
+       database: 'database'
+       username: 'username',
+       password: 'password',
+    })
+    .findMany()
+// users => [{ .... }]
+```
 
+## Backup
+Backup database, you may backup is this:
+```js
 /**
-Folder directory example
-- App
-  - Model
-    Post.ts
-    User.ts
-    Comment.ts
-*/   
-    
-(async () => {
-    const users = await new User()
-        .with('posts','comments') /* relations -> hasMany: posts & comments  */
-        .withQuery('posts', (query) => query.with('user'))   /* relation -> belongsTo: post by user  */
-        .withQuery('comments', (query) => query.with('user','post'))   /* relation -> belongsTo: comment by user? & comment in post*/
-        .findMany()
-        
-    console.log(users)    
-})()
-
-/** 
  * 
- * User.ts
-*/
+ * @param conection defalut current connection
+ */
+const backup = await new DB().backup({
+     database: 'try-to-backup',
+     connection ?: {
+        host: 'localhost..',
+        port : 3306,
+        database: 'database'
+        username: 'username',
+        password: 'password',
+    }
+})
+/**
+ * 
+ * @param conection defalut current connection
+ */
+const backupToFile = await new DB().backupToFile({
+     database: 'try-to-backup',
+     filePath: 'backup.sql',
+     connection ?: {
+        host: 'localhost..',
+        port : 3306,
+        database: 'database'
+        username: 'username',
+        password: 'password',
+  }
+})
+// backupToFile => backup.sql
+```
+
+## 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:
+
+```sh
+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
+```
+## Model Conventions
+Models generated by the make:model command will be placed in the specific directory. 
+Let's examine a basic model class:
+
+```js
 import { Model } from 'tspace-mysql'
+class User extends Model {
+  constructor(){
+    super()
+    this.useTimestamp()
+    /*
+     * the "snake case", plural name of the class will be used as the table name 
+     * 
+     * @param {string} name The table associated with the model.
+     */
+    this.useTable('users')
+  }
+}
+export { User }
+export default User
+```
+## Relationships
+Relationships are defined as methods on your Model classes
+Let's examine a basic relations :
+
+## One To One
+A one-to-one relationship is used to define relationships where a single model is the parent to one child models
+```js
+import { Model } from 'tspace-mysql'
+import Phone  from '../Phone'
 class User extends Model {
     constructor(){
         super()
-        this.hasMany({name : 'posts', model: Post })
-        this.hasMany({name : 'comments', model: Comment })
+        this.useTimestamp()
+        /**
+         *
+         * @hasOne Get the phone associated with the user.
+         * @relationship users.id -> phones.user_id
+         */
+        this.hasOne({ name : 'phone' , model : Phone })
+    }
+    /**
+     * @hasOneQuery Get the phone associated with the user. using function callback
+     * @function 
+     */
+    phone (callback ?: Function) {
+        return  this.hasOneQuery({ model : Phone }, (query) => {
+            return callback ? callback(query) : query
+        })
     }
-} 
+}
 export default User
-/** 
- * 
- * Post.ts
-*/
-import { Model } from 'tspace-mysql'
 
++--------------------------------------------------------------------------+
+
+import User from '../User'
+const user = await new User().with('brand').findOne()
+// user?.phone => {...} 
+const userUsingFunction = await new User().phone().findOne()
+// userUsingFunction?.phone => {...} 
+```
+
+## One To Many
+A one-to-many relationship is used to define relationships where a single model is the parent to one or more child models.
+```js
+import { Model } from 'tspace-mysql'
+import Comment  from '../Comment'
 class Post extends Model {
     constructor(){
         super()
-        this.belongsTo({name : 'user', model: User })
+        this.useTimestamp()
+        /**
+         *
+         * @hasMany Get the comments for the post.
+         * @relationship posts.id -> comments.post_id
+         */
         this.hasMany({ name : 'comments' , model : Comment })
     }
-} 
+    /**
+     * @hasManyQuery Get the comments for the post. using function callback
+     * @function 
+     */
+    comments (callback ?: Function) {
+        return  this.hasManyQuery({ model : Comment }, (query) => {
+            return callback ? callback(query) : query
+        })
+    }
+}
 export default Post
 
-/** 
- * 
- * Comment.ts
-*/
++--------------------------------------------------------------------------+
 
-import { Model } from 'tspace-mysql'
+import Post from '../Post'
+const posts = await new Post().with('comments').findOne()
+// posts?.comments => [{...}]
+const postsUsingFunction = await new Post().comments().findOne()
+// postsUsingFunction?.comments => [{...}]
+```
 
-class Comment extends Model {
+## One To One & One To Many (Inverse) / Belongs To
+```js
+import { Model } from 'tspace-mysql'
+import User  from '../User'
+class Phone extends Model {
     constructor(){
         super()
-        this.belongsTo({name : 'user', model: User })
-        this.belongsTo({name : 'post', model: Post })
+        this.useTimestamp()
+        /**
+         *
+         * @belongsTo Get the user that owns the phone.
+         * @relationship phones.user_id -> users.id
+         */
+        this.belognsTo({ name : 'user' , model : User })
+    }
+    /**
+     * @belongsToQuery Get the user that owns the phone.. using function callback
+     * @function 
+     */
+    user (callback ?: Function) {
+        return  this.belongsToQuery({ model : User }, (query) => {
+            return callback ? callback(query) : query
+        })
     }
-} 
-export default Comment
+}
+export default Phone
+
++--------------------------------------------------------------------------+
+
+import Phone from '../Phone'
+const phone = await new Phone().with('user').findOne()
+// phone?.user => {...}
+const phoneUsingFunction = await new Phone().user().findOne()
+// phoneUsingFunction?.user => {...}
 ```
 
-## Method chaining
+## Many To Many
+Many-to-many relations are slightly more complicated than hasOne and hasMany relationships.
+```js
+import { Model } from 'tspace-mysql'
+import Role from '../Role'
+class User extends Model {
+    constructor(){
+        super()
+        this.useTimestamp()
+        /**
+         *
+         * @belongsToMany Get The roles that belong to the user.
+         * @relationship users.id , roles.id => role_user.user_id , role_user.role_id
+         */
+        this.belognsToMany({ name : 'roles' , model : Role })
+    }
+    /**
+     * @belongsToQuery Get the user that owns the phone.. using function callback
+     * @function 
+     */
+    roles (callback ?: Function) {
+        return  this.belongsToManyQuery({ model : Role }, (query) => {
+            return callback ? callback(query) : query
+        })
+    }
+}
+export default User
+
++--------------------------------------------------------------------------+
+
+import User from '../User'
+const user = await new User().with('roles').findOne()
+// user?.roles => [{...}]
+const userUsingFunction = await new User().roles().findOne()
+// user?.roles => [{...}]
+```
+## Query Builder
 method chaining for queries
 ```js
 where(column , operator , value)   
@@ -210,7 +391,6 @@ whereNull(column)
 whereNotNull(column)
 whereBetween (column , [value1 , value2])
 whereSubQuery(colmn , rawSQL)
-
 select(column1 ,column2 ,...N)
 except(column1 ,column2 ,...N)
 only(column1 ,column2 ,...N)
@@ -224,31 +404,43 @@ having (condition)
 latest (column)
 oldest (column)
 groupBy (column)
-
 create(objects)
 createMultiple(array objects)
 update (objects)
 createNotExists(objects)
 updateOrCreate (objects)
+connection(options)
+backup({ database , connection })
+backupToFile({ filePath, database , connection })
+
 /** 
- * relationship
- * 
- * @Relation setup name in model
+ * registry relation in your models
+ * @relationship
+*/
+hasOne({ name , model , localKey , foreignKey , freezeTable , as }
+hasMany({ name , model , localKey , foreignKey , freezeTable , as }
+belongsTo({ name , model , localKey , foreignKey , freezeTable , as }
+belongsToMany({ name , model , localKey , foreignKey , freezeTable , as }
+/** 
+ * @relation using registry in your models
 */
 with(name1 , name2,...nameN)
+/** 
+ * @relation using registry in your models. if exists child data remove this parent data
+*/
 withExists(name1 , name2,...nameN) 
-withQuery('relation registry',(callback queries))
+/** 
+ * @relation call a relation in registry, callback query of parent data
+*/
+withQuery('relation registry',(callback query))
 
 /**
  * queries statements
- * 
- *  @exec statements
+ * @exec statements
 */
 findMany()
 findOne()
 find(id)
-first()
-get()
 delelte()
 exists ()
 onlyTrashed()
@@ -266,61 +458,64 @@ save() /*for action statements insert update or delete */
 ```
 
 ## Cli
-npm install tspace-mysql -g
-```js
+To get started, let's install npm install tspace-mysql -g
+you may use a basic cli :
 
-tspace-mysql make:model <MODEL NAME> --m  --dir=... --js
-* optional
-    --m  /* created table for migrate */
-    --dir=directory /* created model in directory */ 
-    --type=js /* extension js default ts */
-
-tspace-mysql make:migration <TABLE NAME>
-* optional
-    --type=js /* extension js default ts */
-    --dir=directory /* created table in directory */ 
-    
- tspace-mysql migrate <FOLDER> --js
- * optional
-    --type=js /* extension js default ts */
-    --dir=directory /* find migrate in directory */ 
-```
-
-tspace-mysql make:model User --m --dir=App/Models
-```js
-/* Ex folder 
+## Make Model
+Command will be placed Model in the specific directory
+```sh
+tspace-mysql make:model <MODEL NAME> --m  --dir=.... --type=....
+/** 
+  * @options
+  * --m  // created scheme table for migrate
+  * --dir=directory // created model in directory 
+  * --type=js // extension js default ts
+  */
+  
+tspace-mysql make:model User --m --dir=app/Models  
+// => 
 - node_modules
-- App
+- app
   - Models
      User.ts
 */
-
-/* in App/Models/User.ts */
-import { Model } from 'tspace-mysql'
-class User extends Model{
-  constructor(){
-    super()
-    this.useDebug()  /* default false *debug sql */
-    this.useTimestamp() /* default false * case created_at & updated_at*/
-    this.useSoftDelete()  /*  default false * case where deleted_at is null  */
-    this.useTable('users') /*  default users   */
-    this.usePattern('camelCase') /*  default snake_case  */
-    this.useUUID()
-  }
-}
-export default User
 ```
-tspace-mysql make:migration users --dir=App/Models/Migrations
-```js
-/* Ex folder 
+
+## Make Migration
+Command will be placed Migration in the specific directory
+```sh
+tspace-mysql make:migration <TABLE NAME>
+ /** 
+  * @options
+  * --type=js /* extension js default ts */
+  * --dir=directory /* created table in directory */ 
+  */
+tspace-mysql make:migration users --dir=app/Models/Migrations
+// => 
 - node_modules
-- App
+- app
   - Models
-    - migrations
+    - Migrations
       create_users_table.ts
     User.ts
 */
-/* in App/Models/Migrations/create_users_table.ts */
+```
+## Migrate
+```sh
+ tspace-mysql migrate <FOLDER> --type=...
+ /** 
+  * @options
+  *--type=js /* extension js default ts */
+  *--dir=directory /* find migrate in directory */ 
+  */
+  
+tspace-mysql migrate --dir=App/Models/Migrations
+// => migrate all schema table in folder into database
+```
+
+## Blueprint
+Schema table created by command make:migration,  you may use the:
+```js
 import { Schema , Blueprint , DB } from 'tspace-mysql'
 (async () => {
     await new Schema().table('users',{ 
@@ -333,16 +528,11 @@ import { Schema , Blueprint , DB } from 'tspace-mysql'
         updated_at : new Blueprint().null().timestamp()
     })
     /**
-     * 
-     *  @Faker data
+     *  
+     *  @Faker fake data 5 raw
      *  await new DB().table('users').faker(5)
     */
 })()
-```
-tspace-mysql migrate --dir=App/Models/Migrations
-/* migrate all table in folder into database */
-```js
-* Blueprint method
 /**
  * 
  * @Types
@@ -376,4 +566,4 @@ primary()
 default (string) 
 defaultTimestamp () 
 autoIncrement () 
-```
+```