Initial public reference implementation subsequent to deprecation of

JOQULAR as an in memory datastore.
anywhichway · Feb 11, 2019 · f272137 · f272137
1 parent 3a4a673
commit f272137
Show file tree

Hide file tree

Showing 16 changed files with 1,536 additions and 4,964 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,58 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -1,161 +1,224 @@
 # joqular
 
-NOTE: 
+JavaScript Object Query Language Representation - Funny it's mostly JSON.
 
-2016-10-25: JOQULAR has now been replaced by ReasonDB: https://github.com/anywhichway/reasondb. There were extensive delays due to differences in behavior of Promises in the broweser and  nodejs. Many of these were resolved by moving to asycn/await programming and the use of Babel. Although the pattern matching language is not fully implemented, SQL like functionality and joins are now supported as is persistence in both the browser and on the server. Some of the other feratures in the ALPHA have also be dropped for now. The code base is half the size.
+JOQULAR is a query language specification. Although there is a reference implementation with this site others are free to write their own drivers.
 
-2016-04-28: With the release of Node v6.0 on April 26th, 2016 we are able to re-start development of JOQULAR 2.0 and move from Alpha to Beta in the next month or so.
+# Installation Of Reference Implementation
 
+npm install joqular
 
-An ALPHA of Version 2 of JOQULAR was released on January 10th, 2016. It is available at this branch https://github.com/anywhichway/joqular/tree/v2.  It is recommended you not start using Version 1 for anything other than exploratory investigation and you may simply be better off with the ALPHA. The new version of JOQULAR has the following:
+# Usage
 
-1) A far cleaner code-base.
+```
+const <matched> = await JOQULAR.match(<pattern>,<object>);
+```
 
-2) A more modular code-base.
+```
+const pattern = {name:{$eq:"joe"}},
+	matched1 = await JOQULAR.match(pattern,{name:"joe",age:27}), // will resolve to the object with name "joe"
+	matched2 = await JOQULAR.match(pattern,{name:"jane",age:27}); // will resolve to undefined
+```
 
-3) Movement of temporal code into its own library https://github.com/anywhichway/about-time.
+For now see the [Medium article](https://medium.com/@anywhichway/joqular-high-powered-javascript-pattern-matching-273a0d77eab5) for more information.
 
-4) All predicates and key words now start with $.
+# API
 
-5) Path references now use the key word $self, e.g. {"/": "name"} becomes {$self:"/name"}.
+## Predicates and Functions
 
-6) Native object polyfills are now optional, although not using them will limit database predicate tests against these objects.
+All 92 predicates and functions or their aliases could actually be defined inline; however, functiona that are difficult to implement or used frequently are defined as part of JOQULAR.
 
-7) The calling interface is now almost exclusively Promise based.
+Below is an alphabetical list with minimal documentation. Future documentation will have far more detail and group functions by type. In the meantime, see the the `index.js` in the test directory and review the unit tests.
 
-8) Schema based validation on a continuous basis per property change or a per Object invocation has been added using https://github.com/anywhichway/jovial.
+$
 
-9) Both client and server storage have been added. Transfer of data to the server id accomplished using Faye
+$and 
 
-10) A Node Express starter framework is provided.
+$as
 
+$avg 
 
-JavaScript Object Query Language Representation - Funny, it's mostly JSON.
+$avga 
 
-- Serializable pattern and SQL like object matching for JavaScript, including joins!
-- Use Insert, Update, Delete to modify objects and indexes, or configure indexes to update automatically with zero configuration indexing.
-- More built-in predicates/operators than most other other data query mechanisms, currently 44. Includes built in random and statistical sampling capability.
-- Extensible with just one line of code per predicate/query operator. Puts the intelligence in your data, not the database engine.
-- Just-in-time, fully indexed in-memory database, 2x to 10x faster than linear search, faster than Forerunner, IndexedDB and PouchDB for insert and search.
-- Indexes represent the live state of JavaScript objects. Query results are also live objects or POJO projections, your choice. POJO key value formatting using a built-in or developer specified format function.
-- Extensive Date and Time comparisons with precision at the year, month, day, hour, second, millisecond
-- 3-Way Single Function You Choose API ... callbacks, Promises, return values.
+$between
 
-See the Wiki for detailed documentation: https://github.com/anywhichway/joqular/wiki
+$compute
 
-Issues log and milestones when available: https://github.com/anywhichway/joqular/issues
+$count
 
-Let us know what features you would like us to work on by commenting on any enhancement issues. (Obviously, we will work on bugs.) https://github.com/anywhichway/joqular/issues?utf8=%E2%9C%93&q=label%3Aenhancement+
+$counta
 
-npm install joqular
+$date 
+
+$day
+
+$default
+
+$define 
+
+$descendant
+
+$disjoint 
+
+$echoes 
+
+$eeq 
+
+$eq 
+
+$every 
+
+$excludes 
+
+$extract
+
+$false 
+
+$filter 
+
+$forDescendant 
+
+$freeze 
+
+$fullYear
+
+$gt 
+
+$gte 
+
+$hours 
+
+$in 
+
+$includes 
+
+$instanceof 
+
+$intersects 
+
+$isAny 
+
+$isArray 
+
+$isCreditCard 
+
+$isEmail 
+
+$isEven 
+
+$isFrozen 
+
+$isIPAddress 
+
+$isNaN 
+
+$isOdd 
+
+$isSSN 
+
+$length 
 
-# examples
+$lt 
 
-// everyone named Joe
+$lte 
 
-{name: {$eq: 'Joe'}} 
+$map 
 
-// everyone born in January
+$matches 
 
-{birthday: {month: 1}}
+$max 
 
-// events longer than 1 hour
+$maxa 
 
-{event: {hours: {$gt: 1}}}
+$milliseconds 
 
-// all adult women
+$min 
 
-{age: {$gte: 18}, gender: 'female'}} 
+$mina 
 
-// adult women Bainbridge Island and downtown Seattle
+$minutes 
 
-{age: {$gte: 18}, gender: 'female', address: {zipcode: {$in: [98110,98101]}}}} 
+$month 
 
-// all grandsons named the same as their grandfather
+$ne 
 
-{father: {father: {name: {'/': 'name'}}}} 
+$neeq 
 
-// all partners who are partnered with the same gender
+$neq 
 
-{partner1: {gender: {'..partner2': 'gender'}}}
+$nin 
 
-// all partners who are not partnered with the same gender
+$not 
 
-{partner1: {gender: {$neq: {'..partner2': 'gender'}}}} 
+$or 
 
-// Joe's children, if any are sick
+$outside 
 
-{name: 'Joe', {children: {$some: function(child) { return child.isSick; }}}} 
+$readonly 
 
-// Joe's children, if all are sick
+$redact 
 
-{name: 'Joe', {children: {$every: function(child) { return child.isSick; }}}} 
+$reduce 
 
-// [], unless all females are named Jo
+$regexp 
 
-{gender: 'female', {$forall: function(object) { return object.name==='Jo'; }}} 
+$return 
 
-// all females if any are named Jo
+$sample 
 
-{gender: 'female', {$exists: function(object) { return object.name==='Jo'; }}} 
+$search 
 
-// anyone named Joe or Jo
+$seconds 
 
-{name: {$soundex: 'Joe'}} 
+$some 
 
-// anyone with a name starting in Jo
+$sort 
 
-{name: {$match: /Jo*/}}
+$sum 
 
-// anyone who is female and authorized based on the value, i.e. 21 or over 
+$suma 
 
-function authorized(value) { return value>=21; }.predicate=true;
-{gender: 'female', {age: {$: authorized}}} 
+$text 
 
-// anyone who is female and authorized based on the object, i.e. a volunteer 
+$time 
 
-function authorized() { return this.volunteer }.predicate=true;
-{gender: 'female', $$: authorized}
+$true 
 
-// general query
+$type 
 
-select().from({p1: Person}).where(`<any of the above patterns>`);
+$typeof 
 
-// all Person's ordered by zipcode, then name
+$UTCDate
 
-select().from({p1: Person}).orderBy({'p1.address.zipcode': 'asc', 'p1.name':'asc'});
+$UTCDay
 
- // all combinations of people
-
-select().from({p1: Person,p2: Person}).where({p2: {$neq: p1}});
+$UTCFullYear 
 
-// first 10 Person's matching a query
+$UTCHours 
 
-select().first(10).from({p1: Person}).where(`<any of the above patterns>`);
+$UTCMilliseconds 
 
-// last 10 Person's matching a query
+$UTCMinutes 
 
-select().last(10).from({p1: Person}).where(`<any of the above patterns>`);
+$UTCMonth 
 
-// random sample at 95% confidence +/- 3
+$UTCSeconds     
 
-select().sample(.95,.03).from({p1: Person});
+$valid 
 
-# updates
+$value 
 
-2015-06-01 v1.02.01 Added SQL like Insert, Update, Delete. Further optimized indexing and search. Formatting capability added for POJO projections using Select. Dates fully indexed by year, month, dayofMonth, hours, seconds, milliseconds. Durations fully indexed by years, months, weeks, days,  hours, minutes, seconds, milliseconds. Added weeks (W) to Duration. Three "breaking" changes. 1) Index format changed in a manner that is not compatible with current persisted indexes. No automated migration currently available. 2) Modified syntax to require a $ sign before any function references in patterns and queries in order to provide hints to query optimizer. Simple global replace on an existing function references to address the change. 3) Modified Date, Time, Duration match behavior such they they will no longer match just a number. Dates must be matched using the entire object or their subfields, 'year', 'month', 'dayofMonth', 'hours', 'minutes', 'seconds', 'milliseconds'. Times must be matched using the entire object or their subfield 'milliseconds'. Durations must be matched using the entire object or their subfields 'length' (which is expressed in milliseconds), 'years', 'months', 'weeks', 'days', 'hours', 'seconds', 'milliseconds'. The function 'valueOf()' continues to return a number of milliseconds for all these objects. 
+$where 
 
-2015-05-11 v1.01.02 Extended ability to reference data across patterns when using providers. Reversed ordering of update info and reformatted examples in README. (1,193 Unit tests and growing ...)
+$xor 
 
-2015-05-04 v1.01.01 Added 'between' and 'outside' for primitive types, added SQL like queries with joins, adopted NPM semantic versioning, no breaking changes going from v0.x.xx to v1.xx.xx (1,163 Unit tests and growing ...)
+$year
 
-2015-04-26 v0.0.95 Added missing predicate declaration for String.prototype.match (632 Unit tests and growing ...)
 
-2015-04-26 v0.0.94 Added patterns example, fixed recursion matching issue, added the $$ operator (628 Unit tests and growing ...)
+## Updates
 
-2015-04-25 v0.0.93 corrected typos in npm package  (626 Unit tests and growing ...)
+2019-02-10 v2.0.0b - Initial public reference implementation subsequent to deprecation of JOQULAR as an in memory datastore.
 
-2015-04-25 v0.0.92 Initial public release (626 Unit tests and growing ...)