@routier/core 0.7.0 → 0.8.0

package/dist/plugins/query/QueryOptionsCollection.d.ts

@@ -38,6 +38,9 @@ export declare class QueryOptionsCollection<T> {
      * the shared collection before executing. Without restoring, a re-executed terminal —
      * the whole point of a subscribed queryable — stacks its option a second time and
      * runs it over the first execution's scalar result.
+     *
+     * The item objects are shared with the snapshot. Nothing reports on them, because every
+     * dispatch sends a `forDispatch` copy, so a restore brings back no reports.
      */
     snapshot(): () => void;
     /** Takes an item as it stands — same object, same index, same target and reason. */
@@ -65,14 +68,21 @@ export declare class QueryOptionsCollection<T> {
     reportEngineDivergence(item: QueryCollectionItem<any, any>): void;
     private report;
     /**
-     * Forgets what any previous dispatch reported.
+     * A copy of the collection for one dispatch to a plugin, with nothing reported on it.
      *
      * Capability is answered per dispatch, so a report is only an answer for the execution that
-     * produced it. The items are shared with any snapshot, so a report mutated in place otherwise
-     * survives a restore and a second terminal on the same queryable replays options the plugin
-     * did run — a `skip` applied twice, over rows already windowed.
+     * produced it. Reports are written onto items, and the items of a queryable's collection
+     * outlive any one execution: a snapshot shares them, and a subscription dispatches the same
+     * query on every change. A report left on them replays options the plugin did run on the
+     * next execution, such as a `skip` applied twice over rows already windowed, or hands a
+     * renamed filter to memory that the engine could have run.
+     *
+     * Each item keeps its index, name, value and target. A half from `split`/`splitAt` is copied
+     * with a copy of its origin, and its items are that copy's items, so a report on the half still
+     * cascades over the whole dispatch without reaching the collection it was copied from.
      */
-    forgetReports(): void;
+    forDispatch(): QueryOptionsCollection<T>;
+    private copyForDispatch;
     /** The options the database did not run, in the order they were written. */
     notExecuted(): QueryCollectionItem<any, any>[];
     split(): {

package/dist/plugins/query/index.d.ts

@@ -4,5 +4,6 @@ export * from './formatExplanation';
 export * from './join';
 export * from './Query';
 export * from './QueryOptionsCollection';
+export * from './renames';
 export * from './types';
 export * from './similarity';

package/dist/plugins/query/renames.d.ts

@@ -0,0 +1,27 @@
+import { QueryOptionsCollection } from "./QueryOptionsCollection";
+/**
+ * The options that name a property by what the caller wrote, and so can name a renamed one.
+ *
+ * `sum`, `min`, `max` and `distinct` are not among them: they carry no property, and read what the
+ * `map` in front of them projected. A report on that `map` ends the database phase, so they run in
+ * memory behind it.
+ */
+export type PropertyReadingOption = "filter" | "sort" | "nearest" | "map" | "group";
+/**
+ * Hands back every option over a property stored under a `.from()` name, for the datastore to run
+ * in memory.
+ *
+ * Core keeps such an option with the database, because only the plugin knows whether its backend
+ * reads storage names. One that translates the option — SQL renders the column from
+ * `getResolvedName()` — needs nothing from here. One that runs the caller's lambda over rows as it
+ * stores them reads a key the row does not have, and answers wrongly without an error: that plugin
+ * calls this before it reads anything, and the datastore finishes the query after deserialization,
+ * where the in-memory names exist.
+ *
+ * Reported as `missing-capability`: the backend cannot express the option as written, and like
+ * every capability, that is only knowable by the plugin.
+ *
+ * @param names Which options to check, for a plugin that resolves some of them itself — Mongo renders
+ * filters and sorts through the stored path, and runs `nearest`, `map` and `group` in JavaScript.
+ */
+export declare const reportRenamedProperties: (options: QueryOptionsCollection<any>, names?: readonly PropertyReadingOption[]) => void;

package/dist/plugins/query/types.d.ts

@@ -14,7 +14,16 @@ export type QueryField = {
     sourceName: string;
     destinationName: string;
     isRename: boolean;
+    /** The property the field's value is read from, when it reads exactly one. */
     property?: PropertyInfo<unknown>;
+    /** Every property the field's value is read from. Absent when the selector could not be parsed. */
+    reads?: PropertyInfo<unknown>[];
+    /**
+     * `false` when the value is computed from `property` rather than being it, as in `x.createdDate.getTime()`,
+     * or when the selector could not be parsed. Absent on a field built from a property rather than a
+     * selector, which is that property.
+     */
+    isDirectProperty?: boolean;
     getter: <T>(data: Record<string, unknown>) => T;
 };
 export type QueryOptionExecutionTarget = "database" | "memory";
@@ -28,7 +37,7 @@ export type QueryOptionName = keyof QueryOptionValueMap<unknown>;
  * option after it. Reporting a later one would name a symptom of this one.
  */
 /** Why core planned an option for memory, decided when the option is added. */
-export type MemoryExecutionReason = "not-parsable" | "unmapped-property" | "renamed-property" | "map-rename" | "after-nearest" | "after-join" | "cross-plugin-join" | "predicate-error" | "after-window";
+export type MemoryExecutionReason = "not-parsable" | "unmapped-property" | "map-rename" | "after-nearest" | "after-join" | "cross-plugin-join" | "predicate-error" | "after-window";
 /**
  * What became of an option planned for the database.
  *
@@ -70,11 +79,14 @@ export type QueryOption<T, K extends QueryOptionName> = {
 export type QueryOptionValueMap<T extends {}> = {
     skip: number;
     take: number;
+    /** `property`, `reads` and `isDirectProperty` mean what they do on a {@link QueryField}. */
     sort: {
         selector: GenericFunction<T, T[keyof T]>;
         direction: QueryOrdering;
         propertyName: string;
         property?: PropertyInfo<T> | null;
+        reads?: PropertyInfo<T>[];
+        isDirectProperty?: boolean;
     };
     map: {
         selector: GenericFunction<T, any>;
@@ -101,6 +113,8 @@ export type QueryOptionValueMap<T extends {}> = {
         selector: GenericFunction<T, T[keyof T]>;
         propertyName: string;
         property?: PropertyInfo<T> | null;
+        reads?: PropertyInfo<T>[];
+        isDirectProperty?: boolean;
         vector: number[];
         count: number;
     };

package/dist/plugins/translators/SqlTranslator.d.ts

@@ -1,6 +1,7 @@
 import { QueryOption } from "../query/types";
 import { IQuery } from "../types";
 import { DataTranslator } from "./DataTranslator";
+import { ITranslatedValue } from "./types";
 /**
  * What the statement that produced these rows actually did.
  *
@@ -16,6 +17,20 @@ export type SqlPushdown = {
 export declare class SqlTranslator<TRoot extends {}, TShape> extends DataTranslator<TRoot, TShape> {
     protected readonly pushedDown: SqlPushdown;
     constructor(query: IQuery<TRoot, TShape>, pushedDown?: SqlPushdown);
+    /**
+     * Dates back as Dates, before the caller's selectors run over the rows.
+     *
+     * A `group` key and a `map` are the caller's lambdas, run here over rows as the engine returned them.
+     * SQLite, D1 and libSQL hand a date back as the TEXT it was stored as, which has no `getFullYear()`
+     * and groups apart from the Date the entity holds. Revived at storage paths and in place, which the
+     * datastore's deserialization still reads, and after `decodeJsonColumns`, so a date inside a JSON
+     * column is revived too. Only a string is converted, so an engine that returns a Date (PostgreSQL,
+     * PGlite, MySQL) is left alone, and so is a row already revived.
+     *
+     * Not a joined statement's rows, which are tuples, each half already deserialized. Nor rows whose
+     * `group` or `map` was handed back, which the datastore runs after deserializing them.
+     */
+    translate(data: unknown): ITranslatedValue<TShape>;
     count<TResult extends number>(data: unknown, _: QueryOption<TShape, "count">): TResult;
     min<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "min">): TResult;
     max<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "max">): TResult;

package/dist/schema/SchemaDefinition.d.ts

@@ -36,6 +36,14 @@ export declare class SchemaDefinition<T extends {}> extends SchemaBase<T, any> {
      */
     get '~standard'(): StandardJSONSchemaV1.Props<InferCreateType<T>, InferType<T>>;
     private createReturnFunction;
+    /**
+     * Compiles `builder` into a function taking `fnArgs`.
+     *
+     * A builder with bindings is compiled one level out: an outer function whose parameters are
+     * the bindings, called once here with their values, returns the function that is kept. The
+     * bound values become closure variables of that function, so the per-call cost is a context
+     * read rather than anything resolved by name.
+     */
     private createFunction;
     modify<R>(builder: (d: {
         function: <UU, I = never>(fn: (entity: InferType<CompiledSchema<T>>, collectionName: CollectionName, injected: I) => UU, injected?: I) => SchemaFunction<UU, I, "unmapped">;

package/dist/schema/changeTracker.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Builds the proxy factory that change-tracks an entity.
+ *
+ * Generated schema code receives the result as a bound value — a parameter of the generated
+ * factory — and never refers to this module by name. Name references do not survive a minifier,
+ * which renames the declaration but cannot see inside generated source text (#40, #46). The
+ * returned function holds no per-entity state, so one per compiled schema is shared by every
+ * entity it tracks.
+ */
+export declare function createChangeTracker(): <TEntity extends {}>(entity: TEntity, path?: string, parent?: TEntity) => TEntity;