@routier/core 0.2.0 → 0.3.0

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.
  */

package/dist/expressions/utils.d.ts

@@ -1,10 +1,9 @@
 import { PropertyInfo } from "../schema";
-import { Expression, PropertyExpression } from "./types";
+import { Expression } from "./types";
 /**
  * Extracts all properties referenced in an expression
  * @param expression The expression to analyze
  * @returns Array of PropertyInfo objects referenced in the expression
  */
 export declare function getProperties(expression: Expression): PropertyInfo<any>[];
-export declare function isPropertyExpression(expression: Expression): expression is PropertyExpression;
 export declare function forEach(expression: Expression, callback: (expression: Expression) => boolean): void;