@travetto/model-query 3.0.2 → 3.1.0-rc.0

package/README.md

@@ -1,6 +1,7 @@
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
-<!-- Please modify https://github.com/travetto/travetto/tree/main/module/model-query/DOC.ts and execute "npx trv doc" to rebuild -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/model-query/DOC.tsx and execute "npx trv doc" to rebuild -->
 # Data Model Querying
+
 ## Datastore abstraction for advanced query support.
 
 **Install: @travetto/model-query**
@@ -16,7 +17,7 @@ This module provides an enhanced query contract for [Data Modeling Support](http
 
 ## Contracts
 
-### [Query](https://github.com/travetto/travetto/tree/main/module/model-query/src/service/query.ts#L10)
+### Query
 This contract provides the ability to apply the query support to return one or many items, as well as providing counts against a specific query.
 
 **Code: Query**
@@ -44,7 +45,7 @@ export interface ModelQuerySupport {
 }
 ```
 
-### [Query Crud](https://github.com/travetto/travetto/tree/main/module/model-query/src/service/crud.ts#L11)
+### Crud
 Reinforcing the complexity provided in these contracts, the [Query Crud](https://github.com/travetto/travetto/tree/main/module/model-query/src/service/crud.ts#L11) contract allows for bulk update/deletion by query.  This requires the underlying implementation to support these operations.
 
 **Code: Query Crud**
@@ -66,10 +67,10 @@ export interface ModelQueryCrudSupport extends ModelCrudSupport, ModelQuerySuppo
 }
 ```
 
-### [Facet](https://github.com/travetto/travetto/tree/main/module/model-query/src/service/facet.ts#L12)
+### Facet
 With the complex nature of the query support, the ability to find counts by groups is a common and desirable pattern. This contract allows for faceting on a given field, with query filtering.
 
-**Code: Facet**
+**Code: Query Facet**
 ```typescript
 export interface ModelQueryFacetSupport extends ModelQuerySupport {
   /**
@@ -82,10 +83,10 @@ export interface ModelQueryFacetSupport extends ModelQuerySupport {
 }
 ```
 
-### [Suggest](https://github.com/travetto/travetto/tree/main/module/model-query/src/service/suggest.ts#L12)
+### Suggest
 Additionally, this same pattern avails it self in a set of suggestion methods that allow for powering auto completion and type-ahead functionalities.
 
-**Code: Suggest**
+**Code: Query Suggest**
 ```typescript
 export interface ModelQuerySuggestSupport extends ModelQuerySupport {
   /**
@@ -110,37 +111,36 @@ export interface ModelQuerySuggestSupport extends ModelQuerySupport {
 ```
 
 ## Implementations
-
 |Service|Query|QueryCrud|QueryFacet|
 |-------|-----|---------|----------|
 |[Elasticsearch Model Source](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch#readme "Elasticsearch backing for the travetto model module, with real-time modeling support for Elasticsearch mappings.")|X|X|X|
-|[MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module.")|X|X|X|
-|[SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.")|X|X|X|
+|[MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module.")|X'|X'|X'|
+|[SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.")|X'|X'|X'|
 
 ## Querying
-
 One of the complexities of abstracting multiple storage mechanisms, is providing a consistent query language.  The query language the module uses is a derivation of [mongodb](https://mongodb.com)'s query language, with some restrictions, additions, and caveats. Additionally, given the nature of typescript, all queries are statically typed, and will catch type errors at compile time.
 
 ### General Fields
-   
+
    *  `field: { $eq: T }` to determine if a field is equal to a value
    *  `field: { $ne: T }` to determine if a field is not equal to a value
    *  `field: { $exists: boolean }` to determine if a field exists or not
-   *  `field: T` to see if the field is equal to whatever value is passed in
+   *  `field: T` to see if the field is equal to whatever value is passed in`
 
 ### General Single Valued Fields
-   
+
    *  `field: { $in: T[] }` to see if a record's value appears in the array provided to `$in`
    *  `field: { $nin: T[] }` to see if a record's value does not appear in the array provided to `$in`
 
 ### Ordered Numeric Fields
-   
+
    *  `field: { $lt: number }` checks if value is less than
    *  `field: { $lte: number }` checks if value is less than or equal to
    *  `field: { $gt: number }` checks if value is greater than
    *  `field: { $gte: number }` checks if value is greater than or equal to
+
 ### Ordered Date Fields
-   
+
    *  `field: { $lt: Date | RelativeTime }` checks if value is less than
    *  `field: { $lte: Date | RelativeTime }` checks if value is less than or equal to
    *  `field: { $gt: Date | RelativeTime }` checks if value is greater than
@@ -149,24 +149,23 @@ One of the complexities of abstracting multiple storage mechanisms, is providing
 **Note**: Relative times are strings consisting of a number and a unit.  e.g. -1w or 30d.  These times are always relative to Date.now, but should make building queries more natural.
 
 ### Array Fields
-   
+
    *  `field: { $all: T[]] }` checks to see if the records value contains everything within `$all`
 
 ### String Fields
-   
+
    *  `field: { $regex: RegExp | string; }` checks the field against the regular expression
 
 ### Geo Point Fields
-   
+
    *  `field: { $geoWithin: Point[] }` determines if the value is within the bounding region of the points
-   *  `field: { $near: Point, $maxDistance: number, $unit: 'km' | 'm' | 'mi' | 'ft' }` searches at a point, and looks out radially
+   *  `field: {$near: Point, $maxDistance: number, $unit: 'km' | 'm' | 'mi' | 'ft' }` searches at a point, and looks out radially
 
 ### Groupings
-   
-   *  `{ $and: [] }` provides a grouping in which all sub clauses are required
-   *  `{ $or: [] }` provides a grouping in which at least one of the sub clauses is required
-   *  `{ $not: { } }` negates a clause
 
+   *  `{ $and: [] }` provides a grouping in which all sub clauses are require,
+   *  `{ $or: [] }` provides a grouping in which at least one of the sub clauses is require,
+   *  `{ $not: { } }` negates a clause
 A sample query for `User`'s might be:
 
 **Code: Using the query structure for specific queries**
@@ -203,11 +202,7 @@ export class UserSearch {
 This would find all users who are over `35` and that have the `contact` field specified.
 
 ## Query Language
-
-In addition to the standard query interface, the module also supports querying by query language to facilitate end-user queries.  This is meant to act as an interface that is simpler to write than the default object structure.
-
-The language itself is fairly simple, boolean logic, with parenthetical support.  The operators supported are:
-   
+In addition to the standard query interface, the module also supports querying by query language to facilitate end - user queries.This is meant to act as an interface that is simpler to write than the default object structure. The language itself is fairly simple, boolean logic, with parenthetical support.The operators supported are:
    *  `<`, `<=` - Less than, and less than or equal to
    *  `>`, `>=` - Greater than, and greater than or equal to
    *  `!=`, `==` - Not equal to, and equal to
@@ -216,8 +211,7 @@ The language itself is fairly simple, boolean logic, with parenthetical support.
    *  `in`, `not-in` - Supports checking if a field is in a list of literal values
    *  `and`, `&&` - Intersection of clauses
    *  `or`, `||` - Union of clauses
-
-All sub fields are dot separated for access, e.g. `user.address.city`. A query language version of the previous query could look like:
+All sub fields are dot separated for access, e.g. `user.address.city`.A query language version of the previous query could look like:
 
 **Code: Query language with boolean checks and exists check**
 ```sql
@@ -232,14 +226,10 @@ user.role in ['admin', 'root'] && (user.address.state == 'VA' || user.address.ci
 ```
 
 ### Regular Expression
-
-When querying with regular expressions,patterns can be specified as `'strings'` or as `/patterns/`.  The latter allows for the case insensitive modifier: `/pattern/i`.  Supporting the insensitive flag is up to the underlying model implementation.
+When querying with regular expressions, patterns can be specified as `'strings'` or as `/patterns/`.  The latter allows for the case insensitive modifier: `/pattern/i`.  Supporting the insensitive flag is up to the underlying model implementation.
 
 ## Custom Model Query Service
-In addition to the provided contracts, the module also provides common utilities and shared test suites.  The common utilities are useful for
-repetitive functionality, that is unable to be shared due to not relying upon inheritance (this was an intentional design decision).  This allows for all the [Data Model Querying](https://github.com/travetto/travetto/tree/main/module/model-query#readme "Datastore abstraction for advanced query support.") implementations to completely own the functionality and also to be able to provide additional/unique functionality that goes beyond the interface.
-
-To enforce that these contracts are honored, the module provides shared test suites to allow for custom implementations to ensure they are adhering to the contract's expected behavior.
+In addition to the provided contracts, the module also provides common utilities and shared test suites.The common utilities are useful for repetitive functionality, that is unable to be shared due to not relying upon inheritance(this was an intentional design decision).This allows for all the [Data Model Querying](https://github.com/travetto/travetto/tree/main/module/model-query#readme "Datastore abstraction for advanced query support.") implementations to completely own the functionality and also to be able to provide additional / unique functionality that goes beyond the interface. To enforce that these contracts are honored, the module provides shared test suites to allow for custom implementations to ensure they are adhering to the contract's expected behavior.
 
 **Code: MongoDB Service Test Configuration**
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/model-query",
-  "version": "3.0.2",
+  "version": "3.1.0-rc.0",
   "description": "Datastore abstraction for advanced query support.",
   "keywords": [
     "datastore",
@@ -27,12 +27,12 @@
     "directory": "module/model-query"
   },
   "dependencies": {
-    "@travetto/di": "^3.0.2",
-    "@travetto/model": "^3.0.2",
-    "@travetto/schema": "^3.0.2"
+    "@travetto/di": "^3.1.0-rc.0",
+    "@travetto/model": "^3.1.0-rc.0",
+    "@travetto/schema": "^3.1.0-rc.0"
   },
   "peerDependencies": {
-    "@travetto/test": "^3.0.2"
+    "@travetto/test": "^3.1.0-rc.0"
   },
   "peerDependenciesMeta": {
     "@travetto/test": {

package/support/doc.support.tsx

@@ -0,0 +1,29 @@
+/** @jsxImportSource @travetto/doc */
+import { readFileSync } from 'fs';
+
+import { RootIndex } from '@travetto/manifest';
+import { d, DocJSXElementByFn, DocJSXElement } from '@travetto/doc';
+
+export const Links = {
+  QueryCrud: d.codeLink('Query Crud', '@travetto/model-query/src/service/crud.ts', /export interface/),
+  QueryFacet: d.codeLink('Facet', '@travetto/model-query/src/service/facet.ts', /export interface/),
+  QuerySuggest: d.codeLink('Suggest', '@travetto/model-query/src/service/suggest.ts', /export interface/),
+  Query: d.codeLink('Query', '@travetto/model-query/src/service/query.ts', /export interface/),
+};
+
+export const ModelQueryTypes = (file: string | Function): DocJSXElement[] => {
+  if (typeof file !== 'string') {
+    file = RootIndex.getFunctionMetadata(file)!.source;
+  }
+  const contents = readFileSync(file, 'utf8');
+  const found: DocJSXElementByFn<'CodeLink'>[] = [];
+  const seen = new Set();
+  for (const [, key] of contents.matchAll(/Model(Query(Suggest|Facet|Crud)?)Support/g)) {
+    if (!seen.has(key)) {
+      seen.add(key);
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      found.push(Links[key as keyof typeof Links]);
+    }
+  }
+  return found.map(v => <li>{v}</li>);
+};

package/support/doc.support.ts

@@ -1,29 +0,0 @@
-import { readFileSync } from 'fs';
-
-import { RootIndex } from '@travetto/manifest';
-import { d } from '@travetto/doc';
-import { AllTypeMap } from '@travetto/doc/src/nodes';
-
-export const Links = {
-  QueryCrud: d.SnippetLink('Query Crud', '@travetto/model-query/src/service/crud.ts', /export interface/),
-  QueryFacet: d.SnippetLink('Facet', '@travetto/model-query/src/service/facet.ts', /export interface/),
-  QuerySuggest: d.SnippetLink('Suggest', '@travetto/model-query/src/service/suggest.ts', /export interface/),
-  Query: d.SnippetLink('Query', '@travetto/model-query/src/service/query.ts', /export interface/),
-};
-
-export const ModelQueryTypes = (file: string | Function): AllTypeMap['SnippetLink'][] => {
-  if (typeof file !== 'string') {
-    file = RootIndex.getFunctionMetadata(file)!.source;
-  }
-  const contents = readFileSync(file, 'utf8');
-  const found: AllTypeMap['SnippetLink'][] = [];
-  const seen = new Set();
-  for (const [, key] of contents.matchAll(/Model(Query(Suggest|Facet|Crud)?)Support/g)) {
-    if (!seen.has(key)) {
-      seen.add(key);
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      found.push(Links[key as keyof typeof Links]);
-    }
-  }
-  return found;
-};