@objectstack/service-analytics 17.0.0-rc.4 → 17.0.0-rc.6

package/dist/index.d.cts

@@ -105,23 +105,32 @@ type RelationshipResolver = (baseObject: string, relationshipName: string) => st
  */
 interface DatasetCompileOptions {
     /**
-     * [#5115] The datasource `objectName` DECLARES (`object.datasource`), or
-     * `undefined` when nothing authoritative can answer (no data engine, unknown
-     * object).
+     * [#5115] The datasource `objectName` is BOUND to, or `undefined` when nothing
+     * authoritative can answer (no data engine, unknown object) — or when nothing
+     * binds the object at all and it rides the deployment's default datasource.
      *
      * With it the compiler can settle at COMPILE time what #5033 could only
      * report at QUERY time: a dataset whose join crosses datasources declares a
      * statement no driver can execute, because the analytics engine lowers the
      * whole dataset into ONE SQL statement on the base object's datasource.
      *
-     * IMPORTANT — `'default'` is not an answer. In `ObjectQL.getDriver`'s
-     * resolution order an explicit `object.datasource` other than `'default'`
-     * wins outright (step 1); `'default'` is the schema's DEFAULT value and means
-     * only "no explicit binding", after which routing is decided by
-     * `datasourceMapping` rules, the ADR-0057 §3.6 lifecycle split, and the
-     * owning package's `defaultDatasource` — none of which are visible from here.
-     * The compiler therefore treats `'default'`/`undefined` as UNANSWERED. See
-     * {@link compileDataset}.
+     * [#5288] What the host supplies here changed shape, the rule below did not.
+     * It used to be the object's DECLARED `datasource` — step 1 of the five
+     * `ObjectQL.getDriver` routes by — so an object placed by a
+     * `datasourceMapping` rule, by the ADR-0057 §3.6 lifecycle split, or by its
+     * package's `defaultDatasource` answered `'default'` and was read here as
+     * unanswered. The built-in host (`plugin.ts`) now asks the engine's own
+     * resolver instead, so those three placements ARE visible from here and a join
+     * between two objects bound to two different datasources is decidable
+     * whichever mechanism bound them.
+     *
+     * Still deliberately UNANSWERED: `'default'`, and the object that no rule
+     * places anywhere. The deployment's default driver keeps its natural name
+     * (#3826), so "rides the default" is reported as `undefined` rather than as a
+     * name — which means a join from a bound object to a default-riding one stays
+     * undecidable here and remains the query-time diagnostic's business (#5288
+     * records this boundary; widening it is #5115's follow-up, not this rule's).
+     * See {@link compileDataset}.
      */
     getObjectDatasource?: (objectName: string) => string | undefined;
     /**
@@ -407,6 +416,15 @@ interface AnalyticsServiceConfig {
      * datasources before any query is ever built. Absence keeps the pre-#5115
      * behaviour exactly ("cannot answer, do not block") — the query-time
      * diagnostic above stays as the backstop.
+     *
+     * [#5288] "Bound to" above is the whole contract, and it took until #5288 for
+     * the built-in host to honour it: `plugin.ts` answered with the object's
+     * DECLARED `datasource` — step 1 of the five `ObjectQL.getDriver` routes by —
+     * so an object placed by a `datasourceMapping` rule, by the ADR-0057 §3.6
+     * lifecycle split, or by its package's `defaultDatasource` reported
+     * `'default'` and sent the message above to the wrong database. It now asks
+     * `ObjectQL.resolveEffectiveDatasource`. A custom host owes the same answer:
+     * the datasource an object is BOUND to, `undefined` when nothing binds it.
      */
     getObjectDatasource?: (objectName: string) => string | undefined;
     /**
@@ -665,6 +683,13 @@ declare class AnalyticsService implements IAnalyticsService {
      *   the data path's `resolveQueryFields`: they are engine-assigned rather than
      *   declared, and a gate stricter than the engine it guards would reject
      *   queries that used to work.
+     *
+     * [#5918] Its `stripPrefix` below is deliberately NOT narrowed the way the two
+     * MINTS were. This is a RESOLVER — it mirrors `lookupMember`'s tiers to answer
+     * "which Metric will the strategy read", and that tier order did not change.
+     * What changed is what can reach it: a dotted measure is now either a
+     * `<cube>.` qualifier or a key the cube itself declares, because every other
+     * dotted spelling is refused at the mint before this gate runs.
      */
     private assertMeasureFields;
     /**
@@ -1041,6 +1066,19 @@ declare class DatasetExecutor {
      * ISO strings chronologically, and bucket keys are minted sort-stable.)
      */
     private timeDimensionsOf;
+    /**
+     * The EFFECTIVE bucket size one dimension is grouped at for this selection,
+     * or `undefined` when it is not a date dimension or nothing states a size (in
+     * which case the runtime groups the raw column).
+     *
+     * One definition, two readers, deliberately: {@link buildQuery} uses it to
+     * decide the `GROUP BY`, and {@link runCompare} uses it to realign the
+     * comparison pass's bucket keys (#6007). Those two MUST agree — realigning
+     * `month` keys a query grouped by `quarter` would move every comparison value
+     * onto a bucket that does not exist — and the way to make them agree is to
+     * have one of them, not two that look alike.
+     */
+    private granularityOf;
     private buildQuery;
     private runCompare;
 }
@@ -1464,6 +1502,14 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * string — `String(…)`, the same normalisation `like-pattern.ts` applies at the
      * two SQL emitters and `driver-sql`'s `applyLike` applies at the driver, so one
      * `$contains` means one thing on every face (#5567's invariant).
+     *
+     * [#5234] Those four `String(…)` calls now only ever see a value that renders
+     * faithfully: `fieldLeaves` refuses an object comparand on this family before a
+     * leaf exists. That ordering is load-bearing rather than incidental — this arm
+     * is a PRODUCER for the engine, so stringifying an object here would have
+     * laundered it into `'[object Object]'` and handed a driver a perfectly
+     * well-typed string. A strict driver downstream could never have seen the shape
+     * it was strict about, which is why the guard sits at the door and not here.
      */
     private convertFilter;
     private extractObjectName;

package/dist/index.d.ts

@@ -105,23 +105,32 @@ type RelationshipResolver = (baseObject: string, relationshipName: string) => st
  */
 interface DatasetCompileOptions {
     /**
-     * [#5115] The datasource `objectName` DECLARES (`object.datasource`), or
-     * `undefined` when nothing authoritative can answer (no data engine, unknown
-     * object).
+     * [#5115] The datasource `objectName` is BOUND to, or `undefined` when nothing
+     * authoritative can answer (no data engine, unknown object) — or when nothing
+     * binds the object at all and it rides the deployment's default datasource.
      *
      * With it the compiler can settle at COMPILE time what #5033 could only
      * report at QUERY time: a dataset whose join crosses datasources declares a
      * statement no driver can execute, because the analytics engine lowers the
      * whole dataset into ONE SQL statement on the base object's datasource.
      *
-     * IMPORTANT — `'default'` is not an answer. In `ObjectQL.getDriver`'s
-     * resolution order an explicit `object.datasource` other than `'default'`
-     * wins outright (step 1); `'default'` is the schema's DEFAULT value and means
-     * only "no explicit binding", after which routing is decided by
-     * `datasourceMapping` rules, the ADR-0057 §3.6 lifecycle split, and the
-     * owning package's `defaultDatasource` — none of which are visible from here.
-     * The compiler therefore treats `'default'`/`undefined` as UNANSWERED. See
-     * {@link compileDataset}.
+     * [#5288] What the host supplies here changed shape, the rule below did not.
+     * It used to be the object's DECLARED `datasource` — step 1 of the five
+     * `ObjectQL.getDriver` routes by — so an object placed by a
+     * `datasourceMapping` rule, by the ADR-0057 §3.6 lifecycle split, or by its
+     * package's `defaultDatasource` answered `'default'` and was read here as
+     * unanswered. The built-in host (`plugin.ts`) now asks the engine's own
+     * resolver instead, so those three placements ARE visible from here and a join
+     * between two objects bound to two different datasources is decidable
+     * whichever mechanism bound them.
+     *
+     * Still deliberately UNANSWERED: `'default'`, and the object that no rule
+     * places anywhere. The deployment's default driver keeps its natural name
+     * (#3826), so "rides the default" is reported as `undefined` rather than as a
+     * name — which means a join from a bound object to a default-riding one stays
+     * undecidable here and remains the query-time diagnostic's business (#5288
+     * records this boundary; widening it is #5115's follow-up, not this rule's).
+     * See {@link compileDataset}.
      */
     getObjectDatasource?: (objectName: string) => string | undefined;
     /**
@@ -407,6 +416,15 @@ interface AnalyticsServiceConfig {
      * datasources before any query is ever built. Absence keeps the pre-#5115
      * behaviour exactly ("cannot answer, do not block") — the query-time
      * diagnostic above stays as the backstop.
+     *
+     * [#5288] "Bound to" above is the whole contract, and it took until #5288 for
+     * the built-in host to honour it: `plugin.ts` answered with the object's
+     * DECLARED `datasource` — step 1 of the five `ObjectQL.getDriver` routes by —
+     * so an object placed by a `datasourceMapping` rule, by the ADR-0057 §3.6
+     * lifecycle split, or by its package's `defaultDatasource` reported
+     * `'default'` and sent the message above to the wrong database. It now asks
+     * `ObjectQL.resolveEffectiveDatasource`. A custom host owes the same answer:
+     * the datasource an object is BOUND to, `undefined` when nothing binds it.
      */
     getObjectDatasource?: (objectName: string) => string | undefined;
     /**
@@ -665,6 +683,13 @@ declare class AnalyticsService implements IAnalyticsService {
      *   the data path's `resolveQueryFields`: they are engine-assigned rather than
      *   declared, and a gate stricter than the engine it guards would reject
      *   queries that used to work.
+     *
+     * [#5918] Its `stripPrefix` below is deliberately NOT narrowed the way the two
+     * MINTS were. This is a RESOLVER — it mirrors `lookupMember`'s tiers to answer
+     * "which Metric will the strategy read", and that tier order did not change.
+     * What changed is what can reach it: a dotted measure is now either a
+     * `<cube>.` qualifier or a key the cube itself declares, because every other
+     * dotted spelling is refused at the mint before this gate runs.
      */
     private assertMeasureFields;
     /**
@@ -1041,6 +1066,19 @@ declare class DatasetExecutor {
      * ISO strings chronologically, and bucket keys are minted sort-stable.)
      */
     private timeDimensionsOf;
+    /**
+     * The EFFECTIVE bucket size one dimension is grouped at for this selection,
+     * or `undefined` when it is not a date dimension or nothing states a size (in
+     * which case the runtime groups the raw column).
+     *
+     * One definition, two readers, deliberately: {@link buildQuery} uses it to
+     * decide the `GROUP BY`, and {@link runCompare} uses it to realign the
+     * comparison pass's bucket keys (#6007). Those two MUST agree — realigning
+     * `month` keys a query grouped by `quarter` would move every comparison value
+     * onto a bucket that does not exist — and the way to make them agree is to
+     * have one of them, not two that look alike.
+     */
+    private granularityOf;
     private buildQuery;
     private runCompare;
 }
@@ -1464,6 +1502,14 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * string — `String(…)`, the same normalisation `like-pattern.ts` applies at the
      * two SQL emitters and `driver-sql`'s `applyLike` applies at the driver, so one
      * `$contains` means one thing on every face (#5567's invariant).
+     *
+     * [#5234] Those four `String(…)` calls now only ever see a value that renders
+     * faithfully: `fieldLeaves` refuses an object comparand on this family before a
+     * leaf exists. That ordering is load-bearing rather than incidental — this arm
+     * is a PRODUCER for the engine, so stringifying an object here would have
+     * laundered it into `'[object Object]'` and handed a driver a perfectly
+     * well-typed string. A strict driver downstream could never have seen the shape
+     * it was strict about, which is why the guard sits at the door and not here.
      */
     private convertFilter;
     private extractObjectName;