@webda/ql 4.0.0-beta.2 → 4.0.0-beta.5

package/README.md

@@ -1,3 +1,136 @@
-# @webda/webdaql
+# @webda/ql module
 
-This is a package for WebdaQL, a query language for Webda.
+This module is part of Webda Application Framework that allows you to quickly develop applications with all modern prerequisites: Security, Extensibility, GraphQL, REST, CloudNative [https://webda.io](https://webda.io)
+
+<img src="https://webda.io/images/webda.svg" width="128" />
+
+![CI](https://github.com/loopingz/webda.io/workflows/CI/badge.svg)
+
+[![Join the chat at https://gitter.im/loopingz/webda](https://badges.gitter.im/loopingz/webda.svg)](https://gitter.im/loopingz/webda?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![codecov](https://codecov.io/gh/loopingz/webda.io/branch/main/graph/badge.svg?token=8N9DNM3K3O)](https://codecov.io/gh/loopingz/webda.io)
+[![SonarCloud.io](https://sonarcloud.io/api/project_badges/measure?project=loopingz_webda.io&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=loopingz_webda.io)
+![CodeQL](https://github.com/loopingz/webda.io/workflows/CodeQL/badge.svg)
+
+<!-- README_HEADER -->
+
+## @webda/ql — WebdaQL
+
+A structured query language (WQL) for filtering and paginating Webda Store results. WQL queries are parsed by an ANTLR4 grammar and translated to native backend queries by each Store implementation (in-memory, MongoDB, PostgreSQL, DynamoDB).
+
+### When to use it
+
+You need WQL when you call `store.query()` or a relation's `.query()` method. Every Webda Store accepts a WQL string; no raw SQL, MongoDB filter objects, or DynamoDB conditions needed.
+
+```typescript
+// Query the User repository
+const { results } = await User.getRepository().query(
+  `email = 'alice@example.com' LIMIT 1`
+);
+
+// Query a relation
+const { results: posts } = await user.posts.query(
+  `status = 'published' ORDER BY createdAt DESC LIMIT 10`
+);
+```
+
+### Install
+
+```bash
+npm install @webda/ql
+```
+
+> This package is a dependency of `@webda/core` — you rarely need to install it directly.
+
+### Syntax overview
+
+```
+expression? orderExpression? limitExpression? offsetExpression?
+```
+
+**Filter expressions** support:
+- Comparison: `field = value`, `field != value`, `field > value`, `field >= value`, `field < value`, `field <= value`
+- Pattern match: `field LIKE "pattern"` (`_` = single char, `%` = any chars)
+- Set membership: `field IN [value, value, ...]`
+- Array contains: `field CONTAINS value`
+- Null checks: `field IS NULL`, `field IS NOT NULL` (missing, `undefined` or `null`)
+- Logic: `AND`, `OR`, `( ... )`
+
+**Pagination / ordering:**
+- `ORDER BY field [ASC|DESC], ...`
+- `LIMIT <integer>`
+- `OFFSET "<continuationToken>"`
+
+### Quick examples
+
+```typescript
+import * as WebdaQL from "@webda/ql";
+
+// Parse and evaluate against an in-memory object
+const validator = new WebdaQL.QueryValidator(
+  `status = 'published' AND viewCount >= 100`
+);
+const post = { status: "published", viewCount: 150 };
+console.log(validator.eval(post)); // true
+
+// Prepend a mandatory condition to a user-supplied query
+const merged = WebdaQL.PrependCondition(
+  `status = 'published' ORDER BY title LIMIT 10`,
+  `authorId = 'u-123'`
+);
+// => 'status = "published" AND authorId = "u-123" ORDER BY title ASC LIMIT 10'
+```
+
+### Parameters
+
+Never concatenate user input into a query. Pass values as parameters instead, with `?` and an array or `:name` and an object:
+
+```typescript
+await Task.query("owner = ? AND status IN ?", [user, ["open", "late"]]);
+await Task.query("owner = :owner OR reviewer = :owner", { owner: user });
+
+WebdaQL.bind("priority >= ? LIMIT ?", [2, 10]); // priority >= 2 LIMIT 10
+```
+
+Placeholders are only allowed where a value is expected, values are escaped by type, and `= ?` / `!= ?` with `null` become `IS NULL` / `IS NOT NULL`. Template literals passed straight to a query method are escaped the same way at compile time by `webdac`. See [Parameters](../../docs/pages/Modules/ql/Parameters.md).
+
+### API reference
+
+| Export | Description |
+|--------|-------------|
+| `QueryValidator` | Parses a WQL string; `eval(obj)` evaluates it, `toString()` normalizes it |
+| `bind(query, params)` | Binds `?` / `:name` placeholders to escaped values |
+| `escape(parts, values)` | Escapes template literal values (used by the compile-time rewrite) |
+| `validateSyntax(query)` | Checks a query against the grammar without evaluating it; placeholders allowed |
+| `PrependCondition(query, condition)` | Merges a condition in front of an existing query, preserving ORDER BY / LIMIT / OFFSET |
+| `ExpressionBuilder` | ANTLR visitor that builds the optimized expression AST |
+| `AndExpression` | Logic AND node |
+| `OrExpression` | Logic OR node |
+| `ComparisonExpression` | Comparison leaf node |
+| `Query` | Parsed query result: `{ filter, orderBy?, limit?, continuationToken? }` |
+| `OrderBy` | `{ field: string; direction: "ASC" \| "DESC" }` |
+
+### See also
+
+- [WQL Syntax reference](../../docs/pages/Modules/ql/Syntax.md)
+- [Operators](../../docs/pages/Modules/ql/Operators.md)
+- [Parameters](../../docs/pages/Modules/ql/Parameters.md) — binding values safely
+- [Store Translators](../../docs/pages/Modules/ql/Translators.md) — how each Store backend converts WQL
+
+<!-- README_FOOTER -->
+## Sponsors
+
+<!--
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor](mailto:sponsor@webda.io)
+-->
+
+Arize AI is a machine learning observability and model monitoring platform. It helps you visualize, monitor, and explain your machine learning models. [Learn more](https://arize.com)
+
+[<img src="https://arize.com/hubfs/arize/brand/arize-logomark-1.png" width="200">](https://arize.com)
+
+Loopingz is a software development company that provides consulting and development services. [Learn more](https://loopingz.com)
+
+[<img src="https://loopingz.com/images/logo.png" width="200">](https://loopingz.com)
+
+Tellae is an innovative consulting firm specialized in cities transportation issues. We provide our clients, both public and private, with solutions to support your strategic and operational decisions. [Learn more](https://tellae.fr)
+
+[<img src="https://tellae.fr/" width="200">](https://tellae.fr)

package/lib/WebdaQLLexer.d.ts

@@ -22,19 +22,25 @@ export declare class WebdaQLLexer extends Lexer {
     static readonly LIKE = 17;
     static readonly IN = 18;
     static readonly CONTAINS = 19;
-    static readonly TRUE = 20;
-    static readonly FALSE = 21;
-    static readonly LIMIT = 22;
-    static readonly OFFSET = 23;
-    static readonly ORDER_BY = 24;
-    static readonly ASC = 25;
-    static readonly DESC = 26;
-    static readonly DQUOTED_STRING_LITERAL = 27;
-    static readonly SQUOTED_STRING_LITERAL = 28;
-    static readonly INTEGER_LITERAL = 29;
-    static readonly IDENTIFIER = 30;
-    static readonly IDENTIFIER_WITH_NUMBER = 31;
-    static readonly FUNCTION_IDENTIFIER_WITH_UNDERSCORE = 32;
+    static readonly IS = 20;
+    static readonly NOT = 21;
+    static readonly NULL = 22;
+    static readonly TRUE = 23;
+    static readonly FALSE = 24;
+    static readonly LIMIT = 25;
+    static readonly OFFSET = 26;
+    static readonly ORDER_BY = 27;
+    static readonly ASC = 28;
+    static readonly DESC = 29;
+    static readonly DQUOTED_STRING_LITERAL = 30;
+    static readonly SQUOTED_STRING_LITERAL = 31;
+    static readonly INTEGER_LITERAL = 32;
+    static readonly NUMBER_LITERAL = 33;
+    static readonly POSITIONAL_PARAMETER = 34;
+    static readonly NAMED_PARAMETER = 35;
+    static readonly IDENTIFIER = 36;
+    static readonly IDENTIFIER_WITH_NUMBER = 37;
+    static readonly FUNCTION_IDENTIFIER_WITH_UNDERSCORE = 38;
     static readonly channelNames: string[];
     static readonly modeNames: string[];
     static readonly ruleNames: string[];

package/lib/WebdaQLLexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebdaQLLexer.d.ts","sourceRoot":"","sources":["../src/WebdaQLLexer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKjD,qBAAa,YAAa,SAAQ,KAAK;IACrC,gBAAuB,KAAK,KAAK;IACjC,gBAAuB,UAAU,KAAK;IACtC,gBAAuB,UAAU,KAAK;IACtC,gBAAuB,KAAK,KAAK;IACjC,gBAAuB,iBAAiB,KAAK;IAC7C,gBAAuB,iBAAiB,KAAK;IAC7C,gBAAuB,aAAa,KAAK;IACzC,gBAAuB,aAAa,KAAK;IACzC,gBAAuB,GAAG,KAAK;IAC/B,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,SAAS,MAAM;IACtC,gBAAuB,OAAO,MAAM;IACpC,gBAAuB,gBAAgB,MAAM;IAC7C,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,aAAa,MAAM;IAC1C,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,MAAM,MAAM;IACnC,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,eAAe,MAAM;IAC5C,gBAAuB,UAAU,MAAM;IACvC,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,mCAAmC,MAAM;IAGhE,gBAAuB,YAAY,EAAE,MAAM,EAAE,CAAuC;IAGpF,gBAAuB,SAAS,EAAE,MAAM,EAAE,CAAoB;IAE9D,gBAAuB,SAAS,EAAE,MAAM,EAAE,CAuCxC;IAEF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CA4BpC;IACF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAkCrC;IACF,gBAAuB,UAAU,EAAE,UAAU,CAI3C;IAIF,IAAW,UAAU,IAAI,UAAU,CAElC;gBAGW,KAAK,EAAE,UAAU;IAM7B,IAAW,eAAe,IAAI,MAAM,CAEnC;IAGD,IAAW,SAAS,IAAI,MAAM,EAAE,CAE/B;IAGD,IAAW,aAAa,IAAI,MAAM,CAEjC;IAGD,IAAW,YAAY,IAAI,MAAM,EAAE,CAElC;IAGD,IAAW,SAAS,IAAI,MAAM,EAAE,CAE/B;IAED,gBAAuB,cAAc,EAAE,MAAM,CA6G1B;IACnB,OAAc,KAAK,EAAE,GAAG,CAAC;IACzB,WAAkB,IAAI,IAAI,GAAG,CAM5B;CACF"}
+{"version":3,"file":"WebdaQLLexer.d.ts","sourceRoot":"","sources":["../src/WebdaQLLexer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAE1C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAK1C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAKpD,qBAAa,YAAa,SAAQ,KAAK;IACrC,gBAAuB,KAAK,KAAK;IACjC,gBAAuB,UAAU,KAAK;IACtC,gBAAuB,UAAU,KAAK;IACtC,gBAAuB,KAAK,KAAK;IACjC,gBAAuB,iBAAiB,KAAK;IAC7C,gBAAuB,iBAAiB,KAAK;IAC7C,gBAAuB,aAAa,KAAK;IACzC,gBAAuB,aAAa,KAAK;IACzC,gBAAuB,GAAG,KAAK;IAC/B,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,SAAS,MAAM;IACtC,gBAAuB,OAAO,MAAM;IACpC,gBAAuB,gBAAgB,MAAM;IAC7C,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,aAAa,MAAM;IAC1C,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,MAAM,MAAM;IACnC,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,eAAe,MAAM;IAC5C,gBAAuB,cAAc,MAAM;IAC3C,gBAAuB,oBAAoB,MAAM;IACjD,gBAAuB,eAAe,MAAM;IAC5C,gBAAuB,UAAU,MAAM;IACvC,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,mCAAmC,MAAM;IAGhE,gBAAuB,YAAY,EAAE,MAAM,EAAE,CAAuC;IAGpF,gBAAuB,SAAS,EAAE,MAAM,EAAE,CAAoB;IAE9D,gBAAuB,SAAS,EAAE,MAAM,EAAE,CA6CxC;IAEF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAoCpC;IACF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAwCrC;IACF,gBAAuB,UAAU,EAAE,UAAU,CAI3C;IAIF,IAAW,UAAU,IAAI,UAAU,CAElC;IAGD,YAAY,KAAK,EAAE,UAAU,EAG5B;IAGD,IAAW,eAAe,IAAI,MAAM,CAEnC;IAGD,IAAW,SAAS,IAAI,MAAM,EAAE,CAE/B;IAGD,IAAW,aAAa,IAAI,MAAM,CAEjC;IAGD,IAAW,YAAY,IAAI,MAAM,EAAE,CAElC;IAGD,IAAW,SAAS,IAAI,MAAM,EAAE,CAE/B;IAED,gBAAuB,cAAc,EAAE,MAAM,CAuIU;IACvD,OAAc,KAAK,EAAE,GAAG,CAAC;IACzB,WAAkB,IAAI,IAAI,GAAG,CAM5B;CACF"}