mythix-orm 1.4.2 → 1.4.5

package/docs/Home.md

@@ -1 +1,51 @@
-Welcome to the mythix-orm wiki!
+# Welcome to the Mythix ORM wiki
+
+## Getting started
+
+Here you will not only find documentation for the Mythix ORM API, but also articles (in the "Pages" section) that explain in detail the inner workings of Mythix ORM.
+
+To start with, we highly recommend reading the following articles:
+
+  1. [Query Engine](./QueryEngine)
+  2. [Associations](./Associations)
+
+These should give you a basic idea on how to work with Mythix ORM.
+
+After you have read these articles and understand what you are working with, take a look at the API documentation to understand _what_ you have available to you, and how you can use it.
+
+## What Mythix ORM is (and is not)
+
+Mythix ORM was designed and created to replace all the terrible other options that currently exist for Node. I mean, have you ever looked at the source code for some of the other popular ORM libraries out there? It is the stuff of nightmares!
+
+I was tired of daily having to deal with malarky spewed by the other ORM libraries and their very poorly designed interfaces, their bloat, and their difficulty to setup and use (to say it mildly).
+
+Though I firmly believe ORMs are--in nature--a poor and terrible fix for the plethora if crap us developers must go through daily trying to work with outdated and non-standard databases, they do still have their place in our world (until the database "situation" is resolved). So, while ORMs are still needed, why not at least use the best one available?
+
+Meet Mythix ORM. It was designed from the ground-up to replace *all* other existing ORMs, forever. As part of the design, a few key decisions were made to make Mythix ORM a far better solution than the other "solutions" out there.
+
+Let's go over those key design decisions real quick so we are all on the same page:
+
+  1. Mythix ORM will never be bloated. It has a specific purpose, and it will stick to that purpose. It is an abstraction layer between different database types. It doesn't intend or pretend to be anything else. Mythix ORM is *bare bones*, just what you need, and nothing more. It is the intent and hope of the authors that Mythix ORM will grow a thriving community, and it was a deliberate design decision that the community would build extra libraries to add features to Mythix ORM. The motto over here in Mythix land is "take what you need, and nothing more".
+  2. Mythix ORM is very extensible. Nearly every part of Mythix ORM can be overloaded, hijacked, or replaced entirely. Again, the intent is that the community will provide many cool features through extra libraries that *add* to Mythix ORM's feature set. It was also the intent of the authors who designed Mythix ORM to have it so developers could work with it *the way they like to*, without any of the mandates, and the "world **should** work this way" shenanigans. Mythix ORM is very powerful, and absolutely *will* allow you to shoot yourself in the foot--if you, as the developer, decide that is what you want to do.
+  3. The primary author of this library--Wyatt Greenway--doesn't like the "black box" mentality. Encapsulation is absolutely a must for clean and stable code, but "black box"? Never. For this reason Mythix ORM was designed with no private variables, and nearly every method exists on a class, with the deliberate intent that methods could (and should) be overloaded to provide extra functionality. Please *do* overload methods, and change the behavior of Mythix ORM to fit your team needs. But *please* be a good citizen, and read and understand what you are doing and why before you do it. Mythix ORM will naturally change its interfaces over time (with appropriate versioning applied to each release), and it is up to the downstream developers to update and manage their custom code.
+  4. Mythix ORM deliberately tries to abstract everything it can away from the database. Because of this, you will often find cases where you might need to do things differently then you are used to, or you might find some of our design decisions a little strange. ORMs are *supposed* to be an abstraction layer, so when I see other ORMs suggesting database specific code in their documentation it makes me shudder. Obviously there are times where this can not be avoided, and Mythix ORM does its best to handle these cases in an abstract way. However, there may be times where you just need to make a direct query to do something with your database, or use a custom literal, and that is okay. One area that you will immediately notice this abstraction is the field types. There is a shockingly small number of field types available in Mythix ORM, and this is deliberate. Mythix ORM will *never* supply database specific field types... if you need those, you can use literals, or you can define your own field types to suit your needs. The situation also isn't as bad as you might initially think. Take the `INTEGER` type for example. It is designed such that it can receive as an optional parameter the "number of bytes" needed to store a certain integer type--and then it is up to the specific connection you are using to decide how to implement said type. For example, Mythix ORM does not supply the MySQL specific types like `TINYINT`, `SMALLINT`, or `MEDIUMINT`. Instead, you always simply use `INTEGER`, and specify the number of bytes you need, and the MySQL connection will take care of the rest for you. Field types are just one example. Mythix ORM will abstract away everything it can by deliberate design.
+  5. Mythix ORM and its API were deliberately designed to be as simple as possible, with all the complexity required tucked neatly away in the modular connection drivers. Deliberate intent and lots of thinking went into making the interface simple, yet flexible and powerful. For these reasons Mythix ORM is broken into many pieces, so the developer can pick and choose only what they want. Mythix ORM was also deliberately designed so that it could be run inside a browser. "Why in the heck would I ever do that?" I hear you asking. Well, Mythix ORM has more to offer than just being a layer between databases. Its model system, and especially its query system, are slick, and useful outside the context of server-only. I hope to one day see "browser based" connections that allow developers to use the same powerful query interface built into Mythix ORM inside the browser. I mean, how cool would it be to use the powerful built in query-engine inside the browser? Maybe to generate GraphQL? Or a custom query interface over HTTP? Let's think big and outside the box.
+  6. SQL/NoSQL, who cares? From the ground up Mythix ORM was designed to support SQL and NoSQL (or even completely custom) databases. Connection drivers are painless to create, and the horizon is the limit. Currently Mythix ORM officially only has drivers for `PostgreSQL` and `SQLite`, but in the future it plans (and intends) to support every database on the planet, including file storage systems, and in-memory databases. If you don't see the database driver you are looking for, be patient, or better yet, help out! Before Mythix ORM is considered "done" it will have drivers for `MySQL`, `Microsoft SQL`, `Mongo`, `Snowflake`, `SOLR`, `ElasticSearch`, and many more.
+
+Now let's take a little moment to discuss what Mythix ORM **is not**:
+
+  1. Mythix ORM **is not** bloated, and it never intends to be. We will continue with the modular architecture, giving developers the ability to choose what they want to include (and what they don't want to include). This also means that you, as the developer, need to pay a little more attention. You can't just install Mythix ORM and away you go. You also need to select which database driver you need, and install it manually beside Mythix ORM.
+  2. Mythix ORM **is not** "magical". In fact, we despise "magic" and won't have any of it. Everything must be clearly defined, and must visibly exist somewhere. Mythix ORM will not automatically create fields for you (i.e. `created_at` and `updated_at`), not even for relationships, polymorphic or not. The tedium you may come across was also considered, and accounted for. For example, if you *want* everyone of your models to have a `created_at`, and `updated_at` field, then simply create a base model that all of your other models inherit from, and on the base model itself you can define these "common" fields. The intent is to give the developer full control, while keeping all "magic" off the table.
+  3. Mythix ORM **is not** opinionated. It is actually the opposite. It is the intent of the authors that developers will use and modify this library *exactly how they want to*. We don't make glaring statements like "We won't include a `toSQL` method because no one *should* ever use such a thing!", or silly statements like "You *should* do things our way... because we obviously know best". Ha! Whatever! No, we don't know what is best, and we openly admit it. You, **the developer**, know what is best, and we support you. Do want you want to do, and do it well. Make your mommy proud! Just remember that when you shoot yourself in the foot, it is *your foot*, not ours.
+  4. Mythix ORM **is not** a swiss-army knife, batteries included, does everything under the sun type of library. It can do everything you need it to do however, and it does so in a modular, community supported way. If you want extra features, build them, or rely on what the community builds. Mythix ORM will deliberately always remain small, slim, sleek, and do exactly what it does the best it can, and nothing more.
+  5. We--the authoring team of Mythix ORM--do **not** always know what is best. We know this, and are humble enough to admit it. This is one of the prime reasons behind deciding to lean heavily on the community for support and extra features. When the community builds something that thousands of people are using regularly, then--and only then--will we consider adding it as a core feature to Mythix ORM. In short, we want the community to drive the bus. We will take a back seat and see where it goes, cheering and supporting the entire trip.
+
+## Mythix certifications
+
+Mythix, as a community of libraries, has a certification program. We will certify third party libraries, and we recommend that you select certified libraries first. Why are we doing this? Part of the mission Mythix has is to reengage engineers to actually be engineers, instead of StackOverflow monkeys. We can not even begin to tell you how many times we have wept over the stank we have seen in open source libraries. We would prefer that Mythix, as a community, not be involved in the stank of the rest of the world.
+
+For this reason we will maintain a list of "certified" libraries, whose code bases have been groomed for cleanliness and correctness. We will also maintain a "black list" of libraries that use Mythix technologies, but that have severe stank. We welcome all developers, and hope to build a thriving community around Mythix technologies... but be warned, if you are a poor engineer and poop out poor code, then your project might end up on a blacklist...
+
+The above statements are intended to inspire all developers to become better versions of themselves. Our world is a train wreck of smelly broken code (that is often popular, unfortunately). Mythix hopes to take a hand in changing the landscape, by lifting developers up and supporting good engineers, helping them standout as pillars of hope against the background noise.
+
+We won't be rude, unfair, or bigoted. We will be precise, keen-eyed, care about what we build, and drive engineers to be better engineers. We like the word "accountable", and would like to hold ourselves and our community of engineers to a higher standard. Let's build great things together, not smelly things that everyone hates. Our certification and blacklists will simply serve as a means to try and prod engineers to do a better job, and to aspire to a higher standard.

package/docs/{QueryEngine.md → Query Engine.md }

@@ -383,8 +383,10 @@ Connection interface methods are methods which hand off the query to a connectio
   12. `NOT.LT(...)` (greater than or equal to `>=`)
   13. `LTE(...)` (less than or equal to `<=`)
   14. `NOT.LTE(...)` (greater than `>`)
-  15. `LIKE` **coming soon!**
-  16. `NOT.LIKE` **coming soon!**
+  15. `LIKE(...)` (pattern match `LIKE '%something%'`)
+  16. `LIKE(..., { caseSensitive: true })` (pattern match `LIKE '%something%'`) [only supported in PostgreSQL -- default is `ILIKE`]
+  17. `NOT.LIKE(...)` (not matching pattern `NOT LIKE '%something%'`)
+  18. `NOT.LIKE(..., { caseSensitive: true })` (not matching pattern `NOT LIKE '%something%'`) [only supported in PostgreSQL -- default is `NOT ILIKE`]
 
 ### Control
 

package/lib/connection/connection-base.js

@@ -13,6 +13,10 @@ const Types               = require('../types');
 
 const LiteralBase = Literals.LiteralBase;
 
+/// ConnectionBase is the base class that
+/// all connection classes should inherit from.
+///
+/// Alias: Connection
 class ConnectionBase extends EventEmitter {
   static dialect = 'none';
 

package/lib/connection/query-generator-base.js

@@ -353,28 +353,31 @@ class QueryGeneratorBase {
       let projectedFields = _projectedFields;
       let result;
 
-      // If we are sub-selecting then only the last
-      // field in the projection should be the projection
       if (options && options.isSubQuery) {
-        result = result = Array.from(projectedFields.values());
+        // If we are sub-selecting then only one
+        // field in the projection is allowed
 
-        let lastField = result[result.length - 1];
+        result = Array.from(projectedFields.values());
+        if (result.length !== 1)
+          throw new Error(`${this.constructor.name}::getProjectionFromQueryEngine: Only one field is allowed in the projection of a sub-query.`);
+
+        let subQueryField = result[0];
 
-        if (LiteralBase.isLiteral(lastField))
-          result = [ lastField ];
-        else if (typeof lastField === 'string')
-          result = [ lastField ];
+        if (LiteralBase.isLiteral(subQueryField))
+          result = [ subQueryField ];
+        else if (typeof subQueryField === 'string')
+          result = [ subQueryField ];
         else
-          result = [ new Literals.DistinctLiteral(lastField.fullFieldName) ];
+          result = [ new Literals.DistinctLiteral(subQueryField.fullFieldName) ];
       } else {
+        projectedFields = addRequiredFieldsToProjection(projectedFields);
+
         // If distinct specifies a field, then
         // make sure that field isn't specified twice
         if (hasDistinct) {
           let distinctFieldName = hasDistinct.getFullyQualifiedFieldName();
           if (distinctFieldName)
             projectedFields.delete(distinctFieldName);
-        } else {
-          projectedFields = addRequiredFieldsToProjection(projectedFields);
         }
 
         result = Array.from(projectedFields.values());

package/lib/model.js

@@ -6,12 +6,32 @@ const Type            = require('./types/type');
 const DefaultHelpers  = require('./types/helpers/default-helpers');
 const Field           = require('./field');
 
-// Used as a unique key for cache
+/// Used as a unique key for cache.
+/// Caches will generally be stored in
+/// a Map, and since a Map's keys can
+/// be any instance, we use a "CacheKey"
+/// object on Models that will change
+/// when they are dirty. This will allow
+/// downstream libraries to use this "dirty"
+/// key as a cache key.
 class CacheKey {
+  /// A "number" argument is provided here
+  /// as a way to get an "id" from a CacheKey.
+  /// Another way to view this "number" is
+  /// a cache version. This number is incremented
+  /// every time a model's fields get dirty.
+  ///
+  /// Arguments:
+  ///   number: number
+  ///     An incrementing number, or "version" for the CacheKey
   constructor(number) {
     this.number = (number == null) ? 0 : (number.valueOf() + 1);
   }
 
+  /// Return the "number" or "version"
+  /// of this CacheKey.
+  ///
+  /// Return: number
   valueOf() {
     return this.number;
   }
@@ -85,9 +105,28 @@ function bindStaticWhereToModelClass(ModelClass) {
   });
 }
 
+/// The base Model class for Mythix ORM.
+/// Every Mythix ORM model should inherit
+/// from this class. This class provides
+/// support for all model operations in
+/// Mythix ORM.
 class Model {
+  /// This property assists with type checking
+  ///
+  /// Type: boolean
   static _isMythixModel = true;
 
+  /// Use this method to check if a class
+  /// is a Mythix ORM model. It will return
+  /// `true` if the provided value is a class
+  /// that inherits from <see>Model</see>, or
+  /// if the provided value has an attribute
+  /// named `_isMythixModel` that is truthy.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: Function
+  ///     Value to check.
   static isModelClass(value) {
     if (!value)
       return false;
@@ -101,6 +140,20 @@ class Model {
     return false;
   }
 
+  /// Check to see if the provided value is
+  /// an *instance* of a Mythix ORM <see>Model</see>.
+  /// Unlike <see>Model.isModelClass</see>, which
+  /// checks if a *class* is a <see>Model</see>, this will check
+  /// to see if an *instance* is an instance of a
+  /// Mythix ORM <see>Model</see>. It will return
+  /// `true` if the provided value is an `instanceof`
+  /// <see>Model</see>, or if the values `constructor`
+  /// property has a truthy `_isMythixModel` property.
+  ///
+  /// Return: boolean
+  /// Arguments:
+  ///   value: any
+  ///     Value to check
   static isModel(value) {
     if (!value)
       return false;
@@ -114,6 +167,18 @@ class Model {
     return false;
   }
 
+  /// Like everywhere in Javascript, we can
+  /// call `.toString()` to a get a string
+  /// representation of our <see>Model</see>
+  /// *class*. The optional `showFields` argument,
+  /// if true, will list the models fields as well.
+  /// Without the `showFields` argument, the model
+  /// name alone will be returned as a string.
+  ///
+  /// Return: string
+  /// Arguments:
+  ///   showFields?: boolean
+  ///     If `true`, then list the models fields.
   static toString(showFields) {
     let fieldNames = [];
 
@@ -134,6 +199,30 @@ class Model {
     return this.toString((depth !== 0));
   }
 
+  /// Get the underlying connection bound to
+  /// the model's class. Connection binding is
+  /// optional, so this method can also be provided
+  /// a connection. If a connection is provided, then
+  /// it will simply be returned. Because Mythix ORM
+  /// has no globals, this is a design pattern to
+  /// supply a connection if you have one available,
+  /// or fallback to a "bound" connection (if one can
+  /// be found).
+  ///
+  /// Return: <see>Connection</see>
+  /// Arguments:
+  ///   connection?: <see>Connection</see>
+  ///     An optional connection that can be provided.
+  ///     If provided, it will simply be returned.
+  ///     Otherwise, if not provided, or a falsy value,
+  ///     then attempt to fallback to the bound connection,
+  ///     if any is available.
+  /// Note:
+  ///   An underscore prefix on a method in Mythix ORM
+  ///   implies that this method should not be overloaded
+  ///   unless you know exactly what you are doing.
+  ///   It also implies that there is another method
+  ///   that can and should be overloaded instead.
   static _getConnection(_connection) {
     return _connection || this._mythixBoundConnection;
   }

package/lib/query-engine/field-scope.js

@@ -4,16 +4,21 @@ const Nife            = require('nife');
 const ProxyClass      = require('../proxy-class');
 const QueryEngineBase = require('./query-engine-base');
 
-function addOperatorToQuery(name, inverseName, value) {
+function addOperatorToQuery(name, inverseName, value, extraOptions) {
   if (Nife.instanceOf(value, 'object'))
     throw new Error(`QueryEngine::addOperatorToQuery: ${name}(${value}) makes no sense...`);
 
-  this._addToQuery({
+  let conditionalParams = {
     condition:        true,
     operator:         name,
     inverseOperator:  inverseName,
     value:            this._fetchOperatorValue(value),
-  });
+  };
+
+  if (extraOptions)
+    conditionalParams = Object.assign(conditionalParams, extraOptions);
+
+  this._addToQuery(conditionalParams);
 
   return this._fetchScope('model');
 }
@@ -29,9 +34,6 @@ class FieldScope extends QueryEngineBase {
   }
 
   toString(...args) {
-    if (args.length === 0)
-      return `${this.constructor.name} {}`;
-
     return this.currentContext.queryEngineScope.toString(...args);
   }
 
@@ -86,12 +88,14 @@ class FieldScope extends QueryEngineBase {
     return addOperatorToQuery.call(this, 'LTE', 'GT', value);
   }
 
-  LIKE(value) {
-    return addOperatorToQuery.call(this, 'LIKE', 'NOT_LIKE', value);
+  LIKE(value, options) {
+    let caseSensitive = ((options && options.caseSensitive) === true);
+    return addOperatorToQuery.call(this, 'LIKE', 'NOT_LIKE', value, { caseSensitive });
   }
 
-  NOT_LIKE(value) {
-    return addOperatorToQuery.call(this, 'NOT_LIKE', 'LIKE', value);
+  NOT_LIKE(value, options) {
+    let caseSensitive = ((options && options.caseSensitive) === true);
+    return addOperatorToQuery.call(this, 'NOT_LIKE', 'LIKE', value, { caseSensitive });
   }
 
   [ProxyClass.MISSING](target, prop) {

package/lib/query-engine/model-scope.js

@@ -43,9 +43,6 @@ class ModelScope extends QueryEngineBase {
   }
 
   toString(...args) {
-    if (args.length === 0)
-      return `${this.constructor.name} {}`;
-
     return this.currentContext.queryEngineScope.toString(...args);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythix-orm",
-  "version": "1.4.2",
+  "version": "1.4.5",
   "description": "ORM for Mythix framework",
   "main": "lib/index.js",
   "type": "commonjs",