tspace-mysql 1.0.5 → 1.0.7

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
 
@@ -13,8 +14,18 @@ Install with [npm](https://www.npmjs.com/):
 npm install tspace-mysql --save
 
 ```
-## Setup
-.env
+## Basic Usage
+- [Configuration](#configuration)
+- [Running Queries](#running-queryies)
+- [Database Transactions](#database-transactions)
+- [Accessing Connections](#accessing-connections)
+- [Query Logging](#query-logging)
+- [Generating Model Classes](#generating-model-classes)
+- [Model Conventions](#model-conventions)
+- [Relationships](#relationships)
+
+## 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,174 +33,276 @@ 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'}]
 ```
-
-update data
+Running A Where 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).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'}
++----------------------------------------------------------------------------------+
+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
+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
 ``` 
-
-## Transactions & Rollback
+## Database Transactions 
+Within a database transaction, you may use the:
 ```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
+}
+```
+## 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
-basic model class and discuss some relations:
+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'
-import Post from '../Post'
-import Comment from '../Comment'
-import User from '../User'
-
-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)    
-})()
+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
 ```
-*User.ts
+## 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
++----------------------------------------------------------------------------------+
+import User from '../User'
+const user = await new User().with('brand').findOne()
+// user?.phone => {...} 
+const userUsingFunction = await new User().phone().findOne()
+// userUsingFunction?.phone => {...} 
 ```
 
-*Post.ts
+## 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
++----------------------------------------------------------------------------------+
+import Post from '../Post'
+const posts = await new Post().with('comments').findOne()
+// posts?.comments => [{...}]
+const postsUsingFunction = await new Post().comments().findOne()
+// postsUsingFunction?.comments => [{...}]
 ```
 
-*Comment.ts
+## One To One & One To Many (Inverse) / Belongs To
 ```js
 import { Model } from 'tspace-mysql'
-
-class Comment extends Model {
+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 })
     }
-} 
-export default Comment
+    /**
+     * @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 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 Chaining
 method chaining for queries
 ```js
 where(column , operator , value)   
@@ -209,7 +322,7 @@ select(column1 ,column2 ,...N)
 except(column1 ,column2 ,...N)
 only(column1 ,column2 ,...N)
 hidden(column1 ,column2 ,...N)
-join (primary key , table.foreign key) 
+join(primary key , table.foreign key) 
 rightJoin (primary key , table.foreign key) 
 leftJoin (primary key , table.foreign key) 
 limit (limit)
@@ -219,33 +332,40 @@ latest (column)
 oldest (column)
 groupBy (column)
 
-insert(objects)
 create(objects)
 createMultiple(array objects)
 update (objects)
-insertNotExists(objects)
 createNotExists(objects)
-updateOrInsert (objects)
 updateOrCreate (objects)
+
 /** 
- * 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()
@@ -263,61 +383,64 @@ save() /*for action statements insert update or delete */
 ```
 
 ## Cli
-npm install tspace-mysql -g
-```js
-
-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 */
+To get started, let's install npm install tspace-mysql -g
+you may use a basic cli :
 
-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 method
+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',{ 
@@ -330,16 +453,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 Migrations --dir=App/Models
-/* migrate all table in folder into database */
-```js
-* Blueprint method
 /**
  * 
  * @Types
@@ -373,4 +491,4 @@ primary()
 default (string) 
 defaultTimestamp () 
 autoIncrement () 
-```
+```

package/dist/cli/index.js

@@ -16,12 +16,16 @@ var commands = {
     'migrate': make_3.default
 };
 try {
-    var name = (_c = (_b = (_a = process.argv.slice(2)) === null || _a === void 0 ? void 0 : _a.find(function (data) { return data === null || data === void 0 ? void 0 : data.includes('--name='); })) === null || _b === void 0 ? void 0 : _b.replace('--name=', '')) !== null && _c !== void 0 ? _c : null;
+    var name = (_c = (_b = (_a = process.argv.slice(2)) === null || _a === void 0 ? void 0 : _a.find(function (data) {
+        return data === null || data === void 0 ? void 0 : data.includes('--name=');
+    })) === null || _b === void 0 ? void 0 : _b.replace('--name=', '')) !== null && _c !== void 0 ? _c : null;
     var migrate = (_e = (_d = process.argv.slice(2)) === null || _d === void 0 ? void 0 : _d.includes('--m')) !== null && _e !== void 0 ? _e : false;
-    var dir = (_h = (_g = (_f = process.argv.slice(2)) === null || _f === void 0 ? void 0 : _f.find(function (data) { return data === null || data === void 0 ? void 0 : data.includes('--dir='); })) === null || _g === void 0 ? void 0 : _g.replace('--dir=', '/')) !== null && _h !== void 0 ? _h : null;
-    // const migrateFolder = process.argv.slice(2)?.find(data => data?.includes('--f='))?.replace('--f=','/') ?? null
-    // const type = process.argv.slice(2)?.includes('--js') ?? false ? '.js' : '.ts'
-    var type = (_l = (_k = (_j = process.argv.slice(2)) === null || _j === void 0 ? void 0 : _j.find(function (data) { return data === null || data === void 0 ? void 0 : data.includes('--type='); })) === null || _k === void 0 ? void 0 : _k.replace('--type=', '.')) !== null && _l !== void 0 ? _l : '.ts';
+    var dir = (_h = (_g = (_f = process.argv.slice(2)) === null || _f === void 0 ? void 0 : _f.find(function (data) {
+        return data === null || data === void 0 ? void 0 : data.includes('--dir=');
+    })) === null || _g === void 0 ? void 0 : _g.replace('--dir=', '/')) !== null && _h !== void 0 ? _h : null;
+    var type = (_l = (_k = (_j = process.argv.slice(2)) === null || _j === void 0 ? void 0 : _j.find(function (data) {
+        return data === null || data === void 0 ? void 0 : data.includes('--type=');
+    })) === null || _k === void 0 ? void 0 : _k.replace('--type=', '.')) !== null && _l !== void 0 ? _l : '.ts';
     type = ['.js', '.ts'].includes(type) ? type : '.ts';
     var file = (_o = (_m = process.argv.slice(3)) === null || _m === void 0 ? void 0 : _m.shift()) !== null && _o !== void 0 ? _o : '';
     var cmd = {
@@ -37,5 +41,5 @@ try {
     commands[process.argv[2]](cmd);
 }
 catch (err) {
-    console.log("\n    use make:model <folder/...folder/model name> --m\n    use make:table <folder/folder/...folder> --name=<name>\n    use migrate <folder/folder/...folder> \n");
+    console.log("readme https://www.npmjs.com/package/tspace-mysql");
 }

package/dist/cli/migrate/make.d.ts

@@ -1,4 +1,4 @@
-declare const _default: (_ref: {
+declare const _default: (formCommand: {
     [x: string]: any;
 }) => void;
 export default _default;