tspace-mysql 1.0.8 → 1.1.0

package/README.md

@@ -4,7 +4,7 @@
 [![NPM downloads](https://img.shields.io/npm/dm/tspace-mysql.svg)](https://www.npmjs.com)
 
 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.
+The goal is to always support the latest TypeScript and JavaScript features and provide additional features that help you to develop.
 
 ## Install
 
@@ -14,6 +14,7 @@ Install with [npm](https://www.npmjs.com/):
 npm install tspace-mysql --save
 ```
 ## Basic Usage
+- [Install](#install)
 - [Configuration](#configuration)
 - [Running Queries](#running-queryies)
 - [Database Transactions](#database-transactions)
@@ -24,27 +25,33 @@ npm install tspace-mysql --save
 - [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)
+  - [Belongs To](#belongs-to)
   - [Many To Many](#many-to-many)
+- [Deep Relationships](#deep-relationships) 
 - [Query Builder](#query-builder)
 - [Cli](#cli)
   - [Make Model](#make-model)
   - [Make Migration](#make-migration)
   - [Migrate](#migrate)
 - [Blueprint](#blueprint)
+  - [Types](#types)
+  - [Attrbuites](#attrbuites)
 
 ## 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
+DB_HOST     = localhost
+DB_PORT     = 3306
 DB_USERNAME = root
 DB_PASSWORD = password
 DB_DATABASE = database
 ```
 ## Running Queries
 Once you have configured your database connection, you may run queries is this :
+
 ```js
+
 +-------------+--------------+----------------------------+
 |                     table users                         |
 +-------------+--------------+----------------------------+
@@ -60,14 +67,18 @@ import { DB } from 'tspace-mysql'
     await new DB('users').findOne() //  SELECT * FROM users LIMIT 1 => Object
 })()
 ```
+
 Running A Select Query
+
 ```js
 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'}
@@ -75,6 +86,7 @@ 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',
@@ -92,6 +104,7 @@ 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({
@@ -110,6 +123,7 @@ const { result } = reposity
     // result =>  { id : 1 , username : 'tspace1++', email : 'tspace1++@gmail.com'} 
 ```    
 Running A Delete Query
+
 ```js
 const deleted = await new DB('users').where('id',1).delete()
     // deleted => true
@@ -146,14 +160,15 @@ try {
 
 ## Connection
 When establishing a connection, you may establish options is this:
+
 ```js
 const users = await new DB('users')
     .connection({
-       host: 'localhost..',
-       port : 3306,
-       database: 'database'
-       username: 'username',
-       password: 'password',
+       host     : 'localhost..',
+       port     :  3306,
+       database : 'database'
+       username : 'username',
+       password : 'password',
     })
     .findMany()
 // users => [{ .... }]
@@ -161,34 +176,35 @@ const users = await new DB('users')
 
 ## Backup
 Backup database, you may backup is this:
+
 ```js
 /**
- * 
- * @param conection defalut current connection
+ * @param {string} database created new database
+ * @param {object?} connection [connection=defalut current connection]
  */
 const backup = await new DB().backup({
      database: 'try-to-backup',
-     connection ?: {
-        host: 'localhost..',
-        port : 3306,
-        database: 'database'
-        username: 'username',
-        password: 'password',
+     connection  : {
+        host     : 'localhost..',
+        port     :  3306,
+        database : 'database'
+        username : 'username',
+        password : 'password',
     }
 })
 /**
- * 
- * @param conection defalut current connection
+ * @param {string} database new database
+ * @param {object?} connection [connection=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',
+     connection : {
+        host     : 'localhost..',
+        port     :  3306,
+        database : 'database'
+        username : 'username',
+        password : 'password',
   }
 })
 // backupToFile => backup.sql
@@ -214,20 +230,31 @@ 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 
+    /**
+     * The "snake case", plural name of the class will be used as the table name // => users
      * 
-     * @param {string} name The table associated with the model.
-     */
-    this.useTable('users')
+     * Assign setting global in your model
+     * @useMethod
+     *
+     * this.useDebug() // => runing a uuid (universally unique identifier) when insert new data
+     * this.usePrimaryKey('id') // => runing a uuid (universally unique identifier) when insert new data
+     * this.useTimestamp({ createdAt : 'created_at' , updatedAt : 'updated_at' }) // runing a timestamp when insert or update
+     * this.useSoftDelete()
+     * this.useDisableSoftDeleteInRelations()
+     * this.useTable('users')
+     * this.useTableSingular()
+     * this.useTablePlural()
+     * this.usePattern('snake_case')   
+     * this.useUUID('uuid')
+     * this.useRegistry()
+    */
   }
 }
 export { User }
 export default User
 ```
 ## Relationships
-Relationships are defined as methods on your Model classes
+Relationships are defined as methods on your Model classes.
 Let's examine a basic relations :
 
 ## One To One
@@ -269,6 +296,7 @@ const userUsingFunction = await new User().phone().findOne()
 
 ## 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'
@@ -304,7 +332,7 @@ const postsUsingFunction = await new Post().comments().findOne()
 // postsUsingFunction?.comments => [{...}]
 ```
 
-## One To One & One To Many (Inverse) / Belongs To
+## Belongs To
 ```js
 import { Model } from 'tspace-mysql'
 import User  from '../User'
@@ -341,7 +369,8 @@ const phoneUsingFunction = await new Phone().user().findOne()
 ```
 
 ## Many To Many
-Many-to-many relations are slightly more complicated than hasOne and hasMany relationships.
+Many-to-many relationships are slightly more complicated than hasOne and hasMany relationships.
+
 ```js
 import { Model } from 'tspace-mysql'
 import Role from '../Role'
@@ -376,8 +405,82 @@ const user = await new User().with('roles').findOne()
 const userUsingFunction = await new User().roles().findOne()
 // user?.roles => [{...}]
 ```
+
+## Deep Relationships
+Deep Relationships using methods on your child Model classes.  
+Let's examine a basic relations :
+
+```js
+import { Model } from 'tspace-mysql'
+import Post from '../Post'
+class User extends Model {
+    constructor(){
+        super()
+        this.hasMany({ name : 'posts' , model : Post })
+    }
+}
+export default User
+
++--------------------------------------------------------------------------+
+
+import { Model } from 'tspace-mysql'
+import User from '../User'
+class Comment extends Model {
+    constructor(){
+        super()
+        this.belongsTo({ name : 'user' , model : User })
+    }
+}
+export default Comment
+
++--------------------------------------------------------------------------+
+
+import { Model } from 'tspace-mysql'
+import Comment from '../Comment'
+class Post extends Model {
+    constructor(){
+        super()
+        this.hasMany({ name : 'comments' , model : Comment })
+    }
+}
+export default Post
+
++--------------------------------------------------------------------------+
+
+import Post from '../Post'
+const post = await new Post()
+    .with('comments','user') // => has many comments in posts , => write by user ...
+    .withQuery('comments',(query) => {
+        /**
+          *
+          * @callback query registry in Comment classes 
+          */
+        return query
+            .with('user') // relation this comment by user? 
+            .withQuery('user' , (query) => {
+                return query
+                    .with('posts') // relation this user has many posts ...
+            })
+    })
+    .findOne()
+/* post =>  {
+ *   ....post details,
+ *   comments : [
+ *      {
+ *         ...comment  details,
+ *         user : {
+ *             ...user detils
+ *             posts : [{ ...post details }]
+ *         }
+ *      }
+ *    ],
+ *    user : { ...user detils }
+ * }
+ */
+```
+
 ## Query Builder
-method chaining for queries
+Method chaining for queries
 ```js
 where(column , operator , value)   
 whereSensitive(column , operator , value) 
@@ -416,13 +519,19 @@ backupToFile({ filePath, database , connection })
 /** 
  * 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 }
+ * @param {string} relation.name 
+ * @param {class}  relation.model
+ * @param {string?} relation.as
+ * @param {string?} relation.localKey
+ * @param {string?} relation.foreignKey
+ * @param {string?} relation.freezeTable
+ */
+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
+ * @relation using registry lists in your models
 */
 with(name1 , name2,...nameN)
 /** 
@@ -430,7 +539,7 @@ with(name1 , name2,...nameN)
 */
 withExists(name1 , name2,...nameN) 
 /** 
- * @relation call a relation in registry, callback query of parent data
+ * @relation call name relation in registry, callback query this relation
 */
 withQuery('relation registry',(callback query))
 
@@ -440,6 +549,7 @@ withQuery('relation registry',(callback query))
 */
 findMany()
 findOne()
+findOneOrError(message , options?)
 find(id)
 delelte()
 exists ()
@@ -514,7 +624,7 @@ tspace-mysql migrate --dir=App/Models/Migrations
 ```
 
 ## Blueprint
-Schema table created by command make:migration,  you may use the:
+Schema table created by command make:migration. you may use the:
 ```js
 import { Schema , Blueprint , DB } from 'tspace-mysql'
 (async () => {
@@ -533,11 +643,11 @@ import { Schema , Blueprint , DB } from 'tspace-mysql'
      *  await new DB().table('users').faker(5)
     */
 })()
-/**
- * 
- * @Types
- * 
-*/
+```
+
+## Types
+
+```js
 int ()
 tinyInt (number) 
 bigInt (number)
@@ -552,18 +662,18 @@ text()
 enum(...n)
 date()
 dateTime()
-timestamp ()
-/**
- * 
- * @Attrbuites
- * 
-*/
+timestamp()
+```
+
+## Attrbuites
+
+```js
 unsigned ()
 unique ()
 null ()
 notNull ()
 primary() 
-default (string) 
-defaultTimestamp () 
-autoIncrement () 
+default(string) 
+defaultTimestamp() 
+autoIncrement() 
 ```

package/dist/cli/models/model.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 var Model = function (model, npm) {
-    return "import { Model } from '".concat(npm, "'\nclass ").concat(model, " extends Model {\n  constructor(){\n    super()\n    this.useUUID()\n    this.useTimestamp()\n  }\n}\nexport { ").concat(model, " }\nexport default ").concat(model, "\n");
+    return "import { Model } from '".concat(npm, "'\nclass ").concat(model, " extends Model {\n  constructor(){\n    super()\n    /**\n     * \n     * Assign setting global in your model\n     * @useMethod\n     *\n     * this.useDebug() // => runing a uuid (universally unique identifier) when insert new data\n     * this.usePrimaryKey('id') // => runing a uuid (universally unique identifier) when insert new data\n     * this.useTimestamp({ createdAt : 'created_at' , updatedAt : 'updated_at' }) // runing a timestamp when insert or update\n     * this.useSoftDelete()\n     * this.useDisableSoftDeleteInRelations()\n     * this.useTable('Users')\n     * this.useTableSingular()\n     * this.useTablePlural()\n     * this.usePattern('snake_case')   \n     * this.useUUID('uuid')\n     * this.useRegistry()\n    */\n  }\n}\nexport { ").concat(model, " }\nexport default ").concat(model, "\n");
 };
 exports.default = Model;

package/dist/cli/tables/table.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 var Table = function (table, npm) {
-    return "import { Schema , Blueprint , DB } from '".concat(npm, "'\n(async () => {\n    await new Schema().table('").concat(table, "',{ \n        id :  new Blueprint().int().notNull().primary().autoIncrement(),\n        name : new Blueprint().varchar(120).default('my name'),\n        uuid : new Blueprint().varchar(50),\n        email : new Blueprint().varchar(120).unique(),\n        email_verify : new Blueprint().tinyInt(),\n        password : new Blueprint().varchar(120),\n        birthdate : new Blueprint().date(),\n        created_at : new Blueprint().null().timestamp(),\n        updated_at : new Blueprint().null().timestamp()\n    })\n\n    /**\n     * \n     *  @Faker data\n     *  await new DB().table('").concat(table, "').faker(5)\n    */\n})()\n");
+    return "import { Schema , Blueprint , DB } from '".concat(npm, "'\n(async () => {\n    await new Schema().table('").concat(table, "',{ \n        id :  new Blueprint().int().notNull().primary().autoIncrement(),\n        uuid : new Blueprint().varchar(50),\n        name : new Blueprint().varchar(120).default('my name'),\n        email : new Blueprint().varchar(120).unique(),\n        email_verify : new Blueprint().tinyInt(),\n        password : new Blueprint().varchar(120),\n        birthdate : new Blueprint().date(),\n        created_at : new Blueprint().null().timestamp(),\n        updated_at : new Blueprint().null().timestamp()\n    })\n\n    /**\n     * \n     *  @Faker data\n     *  await new DB().table('").concat(table, "').faker(5)\n    */\n})()\n");
 };
 exports.default = Table;

package/dist/lib/constants/index.js

@@ -132,6 +132,7 @@ var constant = {
         DEBUG: false,
         UUID: false,
         SOFT_DELETE: false,
+        SOFT_DELETE_FORMAT: 'deleted_at',
         SOFT_DELETE_RELATIONS: false,
         RELATION: [],
         WITH: [],

package/dist/lib/tspace/AbstractDatabase.d.ts

@@ -82,6 +82,12 @@ declare abstract class AbstractDatabase {
         page: number;
     }): Promise<Pagination>;
     abstract first(): Promise<any>;
+    abstract firstOrError(message: string, options?: {
+        [key: string]: any;
+    }): Promise<any>;
+    abstract findOneOrError(message: string, options?: {
+        [key: string]: any;
+    }): Promise<any>;
     abstract get(): Promise<any>;
     abstract findOne(): Promise<any>;
     abstract findMany(): Promise<any>;

package/dist/lib/tspace/AbstractModel.d.ts

@@ -1,21 +1,36 @@
-import { Relation } from './Interface';
+import { Relation, RelationQuery } from './Interface';
 import Database from './Database';
 declare abstract class AbstractModel extends Database {
-    abstract useDebug(): void;
-    abstract useTable(table: string): void;
-    abstract useTimestamp(): void;
-    abstract useSoftDelete(): void;
-    abstract usePattern(pattern: string): void;
-    abstract onlyTrashed(): void;
-    abstract trashed(): void;
-    abstract restore(): void;
-    abstract with(...nameRelations: string[]): void;
-    abstract withQuery(nameRelations: string, callback: Function): void;
-    abstract withExists(...nameRelations: string[]): void;
-    abstract hasOne({ name, model, localKey, foreignKey, freezeTable, as }: Relation): void;
-    abstract hasMany({ name, model, localKey, foreignKey, freezeTable, as }: Relation): void;
-    abstract belongsTo({ name, model, localKey, foreignKey, freezeTable, as }: Relation): void;
-    abstract belongsToMany({ name, model, localKey, foreignKey, freezeTable, as }: Relation): void;
+    abstract useUUID(): this;
+    abstract usePrimaryKey(primaryKey: string): this;
+    abstract useDisableSoftDeleteInRelations(): this;
+    abstract useRegistry(): this;
+    abstract useDebug(): this;
+    abstract useTable(table: string): this;
+    abstract useTablePlural(): this;
+    abstract useTableSingular(): this;
+    abstract useTimestamp(): this;
+    abstract useSoftDelete(): this;
+    abstract usePattern(pattern: string): this;
+    abstract onlyTrashed(): Promise<any>;
+    abstract trashed(): Promise<any>;
+    abstract restore(): Promise<any>;
+    abstract ignoreSoftDelete(): this;
+    abstract disableSoftDelete(): this;
+    abstract registry(func: {
+        [key: string]: Function;
+    }): this;
+    abstract with(...nameRelations: string[]): this;
+    abstract withQuery(nameRelations: string, callback: Function): this;
+    abstract withExists(...nameRelations: string[]): this;
+    abstract hasOne({ name, model, localKey, foreignKey, freezeTable, as }: Relation): this;
+    abstract hasMany({ name, model, localKey, foreignKey, freezeTable, as }: Relation): this;
+    abstract belongsTo({ name, model, localKey, foreignKey, freezeTable, as }: Relation): this;
+    abstract belongsToMany({ name, model, localKey, foreignKey, freezeTable, as }: Relation): this;
+    abstract hasOneQuery({ name, model, localKey, foreignKey, freezeTable, as }: RelationQuery, callback: Function): this;
+    abstract hasManyQuery({ name, model, localKey, foreignKey, freezeTable, as }: RelationQuery, callback: Function): this;
+    abstract belongsToQuery({ name, model, localKey, foreignKey, freezeTable, as }: RelationQuery, callback: Function): this;
+    abstract belongsToManyQuery({ name, model, localKey, foreignKey, freezeTable, as }: RelationQuery, callback: Function): this;
 }
 export { AbstractModel };
 export default AbstractModel;

package/dist/lib/tspace/Database.d.ts

@@ -446,6 +446,26 @@ declare class Database extends AbstractDatabase {
     findOne(): Promise<{
         [key: string]: any;
     } | null>;
+    /**
+     *
+     * execute data return object | null
+     * @return {promise<object | null>}
+     */
+    firstOrError(message: string, options?: {
+        [key: string]: any;
+    }): Promise<{
+        [key: string]: any;
+    }>;
+    /**
+     *
+     * execute data return object | null
+     * @return {promise<object | null>}
+     */
+    findOneOrError(message: string, options?: {
+        [key: string]: any;
+    }): Promise<{
+        [key: string]: any;
+    }>;
     /**
      *
      * execute data return Array