@routier/core 0.2.1 → 0.4.0

package/dist/expressions/parser.d.ts

@@ -1,4 +1,23 @@
 import { CompiledSchema } from "../schema";
 import { Expression, Filter, ParamsFilter } from "./types";
 export declare const combineExpressions: (...expressions: Expression[]) => Expression;
+/**
+ * Parses an expression SOURCE FRAGMENT against one schema and one root name.
+ *
+ * `toExpression` starts from a function and works out its own roots. This starts from text, which
+ * is what a caller has when it has split a larger predicate apart — `p.rank > 10` lifted out of
+ * `([p, m]) => p.rank > 10 && m.won === true`.
+ *
+ * **A fragment naming anything other than `rootName` returns `NOT_PARSABLE`, and that is the
+ * point.** It is how a caller discovers which side of a join a conjunct belongs to: parse it
+ * against each side in turn, and exactly one succeeds for a single-side condition. A condition
+ * spanning both fails against both, which is the correct answer — it cannot be pushed to either.
+ *
+ * No params: a fragment carrying a params reference has no bag to resolve it against here, so it
+ * fails rather than binding to nothing.
+ *
+ * Deliberately NOT cached. The cache is keyed by function source, and a fragment is not a function
+ * — two different lambdas can contain the same fragment text against different schemas.
+ */
+export declare const parseFragment: (schema: CompiledSchema<any>, body: string, rootName: string) => Expression;
 export declare const toExpression: <T extends any, P extends any>(schema: CompiledSchema<any>, fn: Filter<T> | ParamsFilter<T, P>, params?: P) => Expression;

package/dist/expressions/types.d.ts

@@ -1,5 +1,53 @@
 import { QueryOptionExecutionTarget } from "../plugins";
-import { PropertyInfo } from "../schema";
+import { CompiledSchemaCore, PropertyInfo } from "../schema";
+/**
+ * JSON-safe form of a literal. Tagged only where JSON cannot carry the value as it is.
+ *
+ * See `Expression.toJson`.
+ */
+export type SerializedValue = {
+    k: "raw";
+    v: string | number | boolean | null;
+} | {
+    k: "date";
+    v: string;
+} | {
+    k: "undefined";
+} | {
+    k: "number";
+    v: "NaN" | "Infinity" | "-Infinity";
+} | {
+    k: "array";
+    v: SerializedValue[];
+};
+/** JSON-safe form of an expression tree. See `Expression.toJson`. */
+export type SerializedExpression = {
+    t: "empty";
+} | {
+    t: "not-parsable";
+} | {
+    t: "operator";
+    operator: Operator;
+    left?: SerializedExpression;
+    right?: SerializedExpression;
+} | {
+    t: "comparator";
+    comparator: Comparator;
+    negated: boolean;
+    strict: boolean;
+    left?: SerializedExpression;
+    right?: SerializedExpression;
+} | {
+    t: "property";
+    path: string;
+    transformer: Transformer | null;
+    locale: string | null;
+} | {
+    t: "value";
+    value: SerializedValue;
+    transformer: Transformer | null;
+    locale: string | null;
+};
 export type ParsedExpression = {
     expression: Expression;
     executionTarget: QueryOptionExecutionTarget;
@@ -19,6 +67,42 @@ export declare abstract class Expression {
     static get NOT_PARSABLE(): NotParsableExpression;
     static isEmpty(expression: Expression): boolean;
     static isNotParsable(expression: Expression): boolean;
+    /**
+     * Turns a tree into plain JSON, so a whole query can cross a wire.
+     *
+     * On the class rather than beside it, because this is the type's own REPRESENTATION — there is one
+     * right answer and it belongs with the thing being represented, next to `EMPTY` and `isEmpty`.
+     * Rendering a tree into some other language (`toSql`, `toMql`, `evaluate`) is a different kind of
+     * thing: there are many, each belongs to its consumer, and none of them is canonical.
+     *
+     * ## Why it is this small
+     *
+     * Of the six node types a bound tree can contain, exactly one holds anything JSON cannot carry:
+     * `PropertyExpression`, whose live `PropertyInfo` has functions, a parent chain and caches. It
+     * reduces to a property PATH — `PropertyInfo.id` IS the dotted path, and `getProperty` is keyed by
+     * exactly that — so rebinding is one lookup.
+     *
+     * `ParamReferenceExpression` never appears: it is a parse-time placeholder that binding replaces
+     * with a plain `ValueExpression` holding the resolved value. A serialized tree is always already
+     * bound, so there is no params object to send alongside it.
+     *
+     * Switches on `type` rather than using the `isXExpression` guards, which live in `../assertions`
+     * and import this module — the guards test the same discriminant, so nothing is lost.
+     */
+    static toJson(expression: Expression): SerializedExpression;
+    /**
+     * Rebuilds a tree from JSON, rebinding every property against `schema`.
+     *
+     * The schema is SUPPLIED rather than read out of the payload. A filter always belongs to a known
+     * collection, and the RECEIVER's schema is the authority on what its properties are — taking an
+     * id from the payload would mean rebinding against a schema the sender chose, which is backwards
+     * for anything crossing a trust boundary.
+     *
+     * @throws when a property path is not declared by `schema`. Not `NOT_PARSABLE`: on a receiver, a
+     * filter that silently stops filtering returns rows the requester excluded, which is the one
+     * failure here worse than an error.
+     */
+    static fromJson(json: SerializedExpression, schema: CompiledSchemaCore<any>): Expression;
 }
 export declare class EmptyExpression extends Expression {
     readonly type: "empty";
@@ -94,8 +178,9 @@ export declare class ValueExpression extends Expression {
 export type ExpressionType = "operator" | "comparator" | "property" | "value" | "empty" | "not-parsable";
 /**
  * Supported value transformations that can be applied to values.
+ * `length` reads the length of a string or array property.
  */
-export type Transformer = "to-lower-case" | "to-upper-case";
+export type Transformer = "to-lower-case" | "to-upper-case" | "length";
 /**
  * Supported comparator operations for expressions.
  */