measurr 0.1.0

package/dist/index-nrjdssft.js

@@ -0,0 +1,200 @@
+import {
+  rootOf,
+  walk
+} from "./index-e6k30sfp.js";
+
+// src/compile.ts
+class CompileError2 extends Error {
+  name = "CompileError";
+}
+function decodeNumber2(value) {
+  if (value === null || value === undefined)
+    return null;
+  if (typeof value === "number")
+    return Number.isNaN(value) ? null : value;
+  if (typeof value === "bigint")
+    return Number(value);
+  if (typeof value === "string") {
+    const parsed = value.trim() === "" ? Number.NaN : Number(value);
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  if (typeof value === "object" && "toNumber" in value && typeof value.toNumber === "function") {
+    return decodeNumber2(value.toNumber());
+  }
+  return null;
+}
+function renderStatement2(statement, renderer) {
+  return new RenderContext(renderer, statement.now).render(statement);
+}
+
+class RenderContext {
+  renderer;
+  now;
+  aliases = new Map;
+  usedAliases = new Set;
+  values = [];
+  constructor(renderer, now) {
+    this.renderer = renderer;
+    this.now = now;
+  }
+  render(statement) {
+    const r = this.renderer;
+    const nodes = [
+      ...statement.select.map((item) => item.node),
+      ...statement.where
+    ];
+    const joins = collectJoins(nodes, statement.from, statement.virtualJoins);
+    const select = statement.select.map((item) => `${this.expr(item.node)} AS ${r.quote(item.alias)}`);
+    const lines = [
+      `SELECT ${select.join(", ")}`,
+      `FROM ${this.tableSource(statement.from, joins)}`
+    ];
+    if (statement.where.length > 0) {
+      lines.push(`WHERE ${statement.where.map((node) => this.expr(node)).join(" AND ")}`);
+    }
+    if (statement.groupBy.length > 0) {
+      const refs = statement.groupBy.map((index) => {
+        if (!statement.select[index])
+          throw new CompileError2(`GROUP BY refers to missing select item ${index}`);
+        return String(index + 1);
+      });
+      lines.push(`GROUP BY ${refs.join(", ")}`);
+    }
+    if (statement.orderBy.length > 0) {
+      const refs = statement.orderBy.map(({ index, direction }) => {
+        const item = statement.select[index];
+        if (!item)
+          throw new CompileError2(`ORDER BY refers to missing select item ${index}`);
+        return `${r.quote(item.alias)} ${direction === "asc" ? "ASC" : "DESC"}`;
+      });
+      lines.push(`ORDER BY ${refs.join(", ")}`);
+    }
+    if (statement.limit !== null)
+      lines.push(`LIMIT ${Math.trunc(statement.limit)}`);
+    return { text: lines.join(`
+`), values: this.values };
+  }
+  alias(ref) {
+    const existing = this.aliases.get(ref);
+    if (existing)
+      return existing;
+    const base = ref.alias ?? ref.name;
+    let alias = base;
+    for (let n = 2;this.usedAliases.has(alias); n++)
+      alias = `${base}_${n}`;
+    this.aliases.set(ref, alias);
+    this.usedAliases.add(alias);
+    return alias;
+  }
+  tableSource(root, joins) {
+    const q = this.renderer.quote;
+    const parts = [`${q(root.name)} AS ${q(this.alias(root))}`];
+    for (const join of joins) {
+      const keyword = join.type === "left" ? "LEFT JOIN" : "INNER JOIN";
+      const source = `${q(join.table.name)} AS ${q(this.alias(join.table))}`;
+      parts.push(`${keyword} ${source} ON ${this.expr(join.on)}`);
+    }
+    return parts.join(" ");
+  }
+  existsSubquery(table, where) {
+    const from = this.tableSource(table, collectJoins([where], table, []));
+    return `SELECT 1 FROM ${from} WHERE ${this.expr(where)}`;
+  }
+  param(value) {
+    const index = this.values.length + 1;
+    const { placeholder, value: bound } = this.renderer.param(value, index);
+    this.values.push(bound);
+    return placeholder;
+  }
+  expr(node) {
+    const r = this.renderer;
+    switch (node.kind) {
+      case "column":
+        return `${r.quote(this.alias(node.table))}.${r.quote(node.column)}`;
+      case "param":
+        return this.param(node.value);
+      case "minutesAgo":
+        return this.param(new Date(this.now.getTime() - node.minutes * 60000));
+      case "compare":
+        return `(${this.expr(node.left)} ${node.op} ${this.expr(node.right)})`;
+      case "logical": {
+        if (node.items.length === 0)
+          return node.op === "and" ? "(1 = 1)" : "(1 = 0)";
+        const joiner = node.op === "and" ? " AND " : " OR ";
+        return `(${node.items.map((item) => this.expr(item)).join(joiner)})`;
+      }
+      case "not":
+        return `(NOT ${this.expr(node.item)})`;
+      case "isNull":
+        return `(${this.expr(node.item)} IS ${node.negated ? "NOT " : ""}NULL)`;
+      case "in": {
+        if (node.values.length === 0)
+          return node.negated ? "(1 = 1)" : "(1 = 0)";
+        const values = node.values.map((value) => this.expr(value)).join(", ");
+        return `(${this.expr(node.item)} ${node.negated ? "NOT IN" : "IN"} (${values}))`;
+      }
+      case "case": {
+        const branches = node.branches.map((branch) => `WHEN ${this.expr(branch.when)} THEN ${this.expr(branch.result)}`).join(" ");
+        const otherwise = node.otherwise ? ` ELSE ${this.expr(node.otherwise)}` : "";
+        return `(CASE ${branches}${otherwise} END)`;
+      }
+      case "exists": {
+        const body = this.existsSubquery(node.table, node.where);
+        return `(${node.negated ? "NOT " : ""}EXISTS (${body}))`;
+      }
+      case "coalesce":
+        return `coalesce(${node.items.map((item) => this.expr(item)).join(", ")})`;
+      case "arithmetic": {
+        const left = this.expr(node.left);
+        const right = this.expr(node.right);
+        if (node.op === "/")
+          return r.divide(left, right);
+        return `(${left} ${node.op} ${right})`;
+      }
+      case "lower":
+        return `lower(${this.expr(node.item)})`;
+      case "toText":
+        return r.toText(this.expr(node.item));
+      case "aggregate":
+        return r.aggregate(node.fn, node.arg ? this.expr(node.arg) : null, node.where ? this.expr(node.where) : null);
+      case "timeBucket":
+        return r.timeBucket(node.unit, this.expr(node.item), node.timezone);
+      case "timePart":
+        return r.timePart(node.part, this.expr(node.item), node.timezone);
+    }
+  }
+}
+function collectJoins(nodes, root, virtualJoins) {
+  const virtualByRoot = new Map(virtualJoins.map((join) => [join.table, join]));
+  const ordered = [];
+  const added = new Set([root]);
+  const visit = (node) => walk(node, (inner) => {
+    if (inner.kind !== "column")
+      return;
+    const columnRoot = rootOf(inner.table);
+    if (columnRoot === root || virtualByRoot.has(columnRoot))
+      ensure(inner.table);
+  });
+  const ensure = (ref) => {
+    if (added.has(ref))
+      return;
+    if (ref.join) {
+      ensure(ref.join.parent);
+      added.add(ref);
+      visit(ref.join.on);
+      ordered.push({ table: ref, type: ref.join.type, on: ref.join.on });
+      return;
+    }
+    const virtual = virtualByRoot.get(ref);
+    if (!virtual)
+      return;
+    added.add(ref);
+    visit(virtual.on);
+    ordered.push(virtual);
+  };
+  for (const node of nodes)
+    visit(node);
+  return ordered;
+}
+
+export { CompileError2, decodeNumber2, renderStatement2 };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { type Analytics, AnalyticsError, type AnalyticsErrorCode, type AnalyticsErrorDetails, type AnalyticsErrorOf, type AnalyticsOptions, type AnalyticsQuery, type AnalyticsQueryEvent, type AnalyticsResult, type AnalyticsSource, createAnalytics, type DatasetCatalogEntry, isAnalyticsError } from './analytics.js';
+export { CompileError, type CompiledStatement, type Dialect, type JoinClause, type SelectItem, type SelectStatement, type SqlRenderer, decodeNumber, renderStatement } from './compile.js';
+export { type AnyDataset, type AnyDimension, type AnyMeasure, type Dataset, type DimensionValue, defineDataset, dimension, type MeasureValue, measure, type Ratio } from './dataset.js';
+export { and, caseWhen, coalesce, type ColumnKey, eq, Expr, type ExprNode, exists, gt, gte, inList, isNotNull, isNull, literal, lt, lte, minutesAgo, ne, not, or, type SqlType, Table, type TableRef, table, toText } from './expr.js';
+export { analyticsToolGuidance } from './guidance.js';
+export type { PeriodInput, PeriodPreset } from './period.js';
+export { AnalyticsResultSchema, type DatasetFilter, type DatasetQuery, type QueryResult, type ResultOf } from './query.js';

package/dist/index.js

@@ -0,0 +1,78 @@
+import {
+  AnalyticsResultSchema2,
+  AnalyticsError2,
+  isAnalyticsError2,
+  createAnalytics2,
+  measure2,
+  dimension2,
+  defineDataset2
+} from "./index-m0czpsyv.js";
+import {
+  CompileError2,
+  decodeNumber2,
+  renderStatement2
+} from "./index-nrjdssft.js";
+import {
+  Expr2,
+  Table2,
+  table2,
+  literal2,
+  eq2,
+  ne2,
+  gt2,
+  gte2,
+  lt2,
+  lte2,
+  and2,
+  or2,
+  not2,
+  isNull2,
+  isNotNull2,
+  caseWhen2,
+  exists2,
+  coalesce2,
+  inList2,
+  toText2,
+  minutesAgo2
+} from "./index-e6k30sfp.js";
+// src/guidance.ts
+var analyticsToolGuidance = `- Answer every "how many", "how much", "per week" or "split by" question with the analytics tool. Never count by hand from lists or pages.
+- Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.
+- Say which period and filters the numbers cover, using the dates in the result ("1-30 September").
+- Compare with the previous period (compareToPrevious) when the change is the point, such as "is it going up".
+- When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.
+- Ask one short question only when the period is genuinely ambiguous ("this season") and someone can answer; otherwise take the natural reading and state it.`;
+export {
+  AnalyticsError2 as AnalyticsError,
+  AnalyticsResultSchema2 as AnalyticsResultSchema,
+  CompileError2 as CompileError,
+  Expr2 as Expr,
+  Table2 as Table,
+  analyticsToolGuidance,
+  and2 as and,
+  caseWhen2 as caseWhen,
+  coalesce2 as coalesce,
+  createAnalytics2 as createAnalytics,
+  decodeNumber2 as decodeNumber,
+  defineDataset2 as defineDataset,
+  dimension2 as dimension,
+  eq2 as eq,
+  exists2 as exists,
+  gt2 as gt,
+  gte2 as gte,
+  inList2 as inList,
+  isAnalyticsError2 as isAnalyticsError,
+  isNotNull2 as isNotNull,
+  isNull2 as isNull,
+  literal2 as literal,
+  lt2 as lt,
+  lte2 as lte,
+  measure2 as measure,
+  minutesAgo2 as minutesAgo,
+  ne2 as ne,
+  not2 as not,
+  or2 as or,
+  renderStatement2 as renderStatement,
+  table2 as table,
+  toText2 as toText
+};

package/dist/period.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Periods are whole local days in the tenant's timezone. A period `{ from, to }` covers
+ * `from` 00:00 up to (not including) the day after `to` 00:00, converted to instants, so the
+ * database compares plain timestamps and can use its time index.
+ */
+export type PeriodPreset = 'today' | 'yesterday' | 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth' | 'thisYear';
+export type PeriodInput = {
+    last: {
+        days: number;
+    };
+} | {
+    from: string;
+    to: string;
+} | {
+    preset: PeriodPreset;
+};
+export type ResolvedPeriod = {
+    /** First local day, `YYYY-MM-DD`. */
+    from: string;
+    /** Last local day, inclusive. */
+    to: string;
+    timezone: string;
+    /** Inclusive start instant. */
+    start: Date;
+    /** Exclusive end instant. */
+    end: Date;
+    days: number;
+};
+export declare const MAX_PERIOD_DAYS = 731;
+export declare const DEFAULT_PERIOD: PeriodInput;
+/** True for an IANA name the runtime knows. Names are also inlined in SQL, so be strict. */
+export declare function isValidTimezone(timezone: string): boolean;
+/** The local calendar date of `instant` in `timezone`, as `YYYY-MM-DD`. */
+export declare function localDate(instant: Date, timezone: string): string;
+/** The instant local midnight starts on `date` in `timezone` (handles DST changes). */
+export declare function startOfLocalDay(date: string, timezone: string): Date;
+export declare function addDays(date: string, days: number): string;
+export declare class PeriodError extends Error {
+    readonly name = "PeriodError";
+}
+/** Resolves a period input to local days and instants in `timezone`. */
+export declare function resolvePeriod(input: PeriodInput, timezone: string, now: Date): ResolvedPeriod;
+/** The period of equal length that ends the day before `period` starts. */
+export declare function previousPeriod(period: ResolvedPeriod): ResolvedPeriod;

package/dist/plan.d.ts

@@ -0,0 +1,86 @@
+import type { Dialect, SelectStatement } from './compile.js';
+import type { AnyDataset } from './dataset.js';
+import { type PeriodInput, type ResolvedPeriod } from './period.js';
+/** A parsed query with every default filled in and duplicates removed. */
+export type NormalizedQuery = {
+    dataset: string;
+    measures: string[];
+    groupBy: string[];
+    filters: NormalizedFilter[];
+    period: PeriodInput;
+    time: string;
+    compareToPrevious: boolean;
+    sort: {
+        by: string;
+        direction: 'asc' | 'desc';
+    } | null;
+    limit: number;
+};
+export type NormalizedFilter = {
+    dimension: string;
+    op: 'in' | 'notIn';
+    values: (string | number)[];
+} | {
+    dimension: string;
+    op: 'between';
+    from: string | number;
+    to: string | number;
+} | {
+    dimension: string;
+    op: 'isEmpty' | 'isNotEmpty';
+};
+/** The parsed shape the schema produces (all optional fields possibly absent). */
+export type ParsedQuery = {
+    dataset: string;
+    measures: readonly string[];
+    groupBy?: readonly string[] | undefined;
+    filters?: readonly NormalizedFilter[] | undefined;
+    period?: PeriodInput | undefined;
+    time?: string | undefined;
+    compareToPrevious?: boolean | undefined;
+    sort?: {
+        by: string;
+        direction?: 'asc' | 'desc' | undefined;
+    } | undefined;
+    limit?: number | undefined;
+};
+export declare function normalizeQuery(dataset: AnyDataset, parsed: ParsedQuery): NormalizedQuery;
+/** What the planner needs besides the query: values from the hooks and resolved labels. */
+export type PlanContext = {
+    tenant: string | number;
+    timezone: string;
+    period: ResolvedPeriod;
+    /** The moment the query runs. */
+    now: Date;
+    /** Keys for filters on open dimensions, after label resolution, by dimension. */
+    resolvedValues: ReadonlyMap<string, readonly (string | number)[]>;
+};
+/** Output column aliases. Keys come from definitions, never from input. */
+export declare const columnAlias: {
+    measure: (key: string) => string;
+    groupKey: (key: string) => string;
+    groupLabel: (key: string) => string;
+};
+/**
+ * The statement for a query's rows, or for its totals when `grouped` is false. Totals never
+ * group, so a many-to-many grouping cannot inflate them.
+ */
+export declare function planQuery(dataset: AnyDataset, query: NormalizedQuery, context: PlanContext, grouped: boolean): SelectStatement;
+/**
+ * Looks up an open dimension's keys and names. With `values`, only entries whose key or name
+ * (case-insensitive) matches; without, the first entries by name, to list valid values.
+ */
+export declare function planLookup(dataset: AnyDataset, dimensionKey: string, tenant: string | number, values: readonly string[] | null, now: Date): SelectStatement;
+export type ShapedValue = {
+    key: string | number | null;
+    label: string;
+};
+export type ShapedRow = Record<string, ShapedValue | number | null>;
+/** Decodes measures in one raw row; counts are never null. */
+export declare function shapeMeasures(dataset: AnyDataset, measures: readonly string[], raw: Record<string, unknown>, dialect: Dialect): Record<string, number | null>;
+export declare function shapeRows(dataset: AnyDataset, query: NormalizedQuery, rawRows: readonly Record<string, unknown>[], dialect: Dialect): {
+    rows: ShapedRow[];
+    truncated: boolean;
+};
+/** Notes a reader needs to read the numbers right. */
+export declare function resultNotes(dataset: AnyDataset, query: NormalizedQuery): string[];