@happyvertical/smrt-reports 0.36.5

package/AGENTS.md

@@ -0,0 +1,26 @@
+# @happyvertical/smrt-reports
+
+Materialized aggregate report models for SMRT.
+
+## Key Pieces
+
+| Module | Purpose |
+| --- | --- |
+| `SmrtReport` | Abstract report row base with `refreshedAt`, `isStale()`, and manual `refresh()` |
+| decorators | `@report`, grouping decorators, time buckets, and aggregate measure decorators |
+| compiler | Pure `ReportDefinition -> AggregateSpec` compiler and ObjectRegistry adapter |
+| aggregate | Compatibility re-export of the SDK aggregate query builder |
+| refresh | Rebuild and incremental refresh engine with run tracking, watermarks, locks, and tenant scoping |
+| state | Internal `_smrt_report_*` system models for runs, watermarks, locks, schedules, and refresh tasks |
+| scheduler | Cron schedule runner, durable refresh job enqueueing, and `onChange` interceptor registration |
+
+## Conventions
+
+- Report cache tables are normal `@smrt()` tables. Runtime refresh must not create schema.
+- Store report metadata under field `_meta.__report`; scanner and runtime decorators must stay aligned.
+- Keep SQL generation portable. Use the SDK `buildAggregate()`/`bucketExpr()` helpers for time buckets and `$N` placeholders.
+- Do not add a local aggregate SQL builder here; the implementation lives in `@happyvertical/sql`.
+- Refresh runtime tables are schema-managed. Runtime refresh must fail clearly when `_smrt_report_runs`, `_smrt_report_watermarks`, or `_smrt_report_locks` have not been migrated.
+- Incremental refresh requires a source watermark column (default `updatedAt`) and soft-delete column (default `deletedAt`); it recomputes affected groups and deletes empty report groups instead of applying aggregate deltas.
+- Raw aggregate refreshes must explicitly filter `tenant_id`; the tenancy interceptor only protects normal collection reads.
+- Scheduled/on-change refreshes enqueue `SmrtReportRefreshTask.run()` through `@happyvertical/smrt-jobs`; do not add a separate report queue.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/aggregate.d.ts

@@ -0,0 +1,25 @@
+import { AggregateBuildResult } from '@happyvertical/sql';
+import { AggregateFunction } from '@happyvertical/sql';
+import { AggregateSelectExpr } from '@happyvertical/sql';
+import { AggregateSpec } from '@happyvertical/sql';
+import { AggregateTimeBucketUnit } from '@happyvertical/sql';
+import { bucketExpr } from '@happyvertical/sql';
+import { buildAggregate } from '@happyvertical/sql';
+
+export { AggregateBuildResult }
+
+export { AggregateFunction }
+export { AggregateFunction as ReportAggregateFn }
+
+export { AggregateSelectExpr }
+
+export { AggregateSpec }
+
+export { AggregateTimeBucketUnit }
+export { AggregateTimeBucketUnit as ReportTimeBucketUnit }
+
+export { bucketExpr }
+
+export { buildAggregate }
+
+export { }

package/dist/aggregate.js

@@ -0,0 +1,6 @@
+import { bucketExpr, buildAggregate } from "@happyvertical/sql";
+export {
+  bucketExpr,
+  buildAggregate
+};
+//# sourceMappingURL=aggregate.js.map

package/dist/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/compiler.d.ts

@@ -0,0 +1,78 @@
+import { AggregateFunction } from '@happyvertical/sql';
+import { AggregateSpec } from '@happyvertical/sql';
+import { AggregateTimeBucketUnit } from '@happyvertical/sql';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { WhereClause } from '@happyvertical/sql';
+
+export declare function buildReportDefinition(reportCtor: new (...args: any[]) => SmrtObject): Promise<ReportDefinition>;
+
+export declare function compileReportDefinition(definition: ReportDefinition): AggregateSpec;
+
+export declare function compileReportSpec(reportCtor: new (...args: any[]) => SmrtObject): Promise<AggregateSpec>;
+
+export declare function getReportGroupingColumns(definition: Pick<ReportDefinition, 'fields'>): string[];
+
+declare interface ReportAggregateFieldMetadata {
+    kind: 'aggregate';
+    fn: ReportAggregateFn;
+    column?: string;
+    distinct?: boolean;
+}
+
+declare type ReportAggregateFn = AggregateFunction;
+
+declare interface ReportBucketFieldMetadata {
+    kind: 'bucket';
+    unit: ReportTimeBucketUnit;
+    sourceColumn: string;
+}
+
+declare interface ReportDefinition {
+    reportClassName: string;
+    sourceClassName: string;
+    sourceTable: string;
+    fields: ReportFieldDefinition[];
+    where?: WhereClause;
+    having?: WhereClause;
+    refresh?: ReportRefreshConfig;
+}
+
+declare interface ReportFieldDefinition {
+    fieldName: string;
+    columnName?: string;
+    type?: string;
+    report?: ReportFieldMetadata;
+}
+
+declare type ReportFieldMetadata = ReportGroupFieldMetadata | ReportBucketFieldMetadata | ReportAggregateFieldMetadata;
+
+declare interface ReportGroupFieldMetadata {
+    kind: 'group';
+    sourceColumn?: string;
+}
+
+declare interface ReportRefreshConfig {
+    mode?: ReportRefreshMode;
+    schedule?: string;
+    onChange?: ReportSource[];
+    /**
+     * Milliseconds before collection reads trigger a synchronous refresh.
+     *
+     * TTL refresh checks add a read-time MAX(refreshedAt) query, and stale reads
+     * perform the refresh before returning list/get results.
+     */
+    ttl?: number;
+    manual?: boolean;
+    watermarkColumn?: string;
+    softDeleteColumn?: string;
+    fullRebuildSchedule?: string;
+    tenantFanout?: boolean;
+}
+
+declare type ReportRefreshMode = 'rebuild' | 'incremental';
+
+declare type ReportSource = string | (new (...args: any[]) => SmrtObject) | (abstract new (...args: any[]) => SmrtObject);
+
+declare type ReportTimeBucketUnit = AggregateTimeBucketUnit;
+
+export { }

package/dist/compiler.js

@@ -0,0 +1,218 @@
+import { ObjectRegistry } from "@happyvertical/smrt-core";
+import { toSnakeCase } from "@happyvertical/smrt-core/utils";
+import { getRuntimeReportOptions } from "./decorators.js";
+const REPORT_BASE_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "slug",
+  "context",
+  "created_at",
+  "updated_at",
+  "createdAt",
+  "updatedAt",
+  "refreshedAt"
+]);
+function sourceClassName(source) {
+  if (typeof source === "string") return source;
+  return source.name;
+}
+function reportOptionsFromRegistry(reportCtor) {
+  const registered = ObjectRegistry.getClassByConstructor(reportCtor) ?? ObjectRegistry.getClass(reportCtor.name);
+  return registered?.config?.report;
+}
+function getReportOptions(reportCtor) {
+  const options = getRuntimeReportOptions(reportCtor) ?? reportOptionsFromRegistry(reportCtor);
+  if (!options?.source) {
+    throw new Error(
+      `${reportCtor.name} is missing @report({ source }) metadata. Decorate the report class with @report({ source: SourceClass }).`
+    );
+  }
+  return options;
+}
+function getRegisteredClassName(ctor) {
+  const registered = ObjectRegistry.getClassByConstructor(ctor) ?? ObjectRegistry.getClass(ctor.name);
+  return registered?.qualifiedName ?? registered?.name ?? ctor.name;
+}
+function resolveTableName(className) {
+  const tableName = ObjectRegistry.getTableName(className);
+  if (!tableName) {
+    throw new Error(
+      `No SMRT table registered for ${className}. Ensure the class is decorated with @smrt() and its manifest is loaded.`
+    );
+  }
+  return tableName;
+}
+function parseWhereKey(key) {
+  const trimmed = key.trim();
+  const operators = [
+    " is not null",
+    " is null",
+    " not in",
+    " like",
+    " in",
+    " !=",
+    " >=",
+    " <=",
+    " >",
+    " <",
+    " ="
+  ];
+  const lower = trimmed.toLowerCase();
+  for (const operator of operators) {
+    if (lower.endsWith(operator)) {
+      return {
+        field: trimmed.slice(0, -operator.length).trim(),
+        suffix: operator
+      };
+    }
+  }
+  return { field: trimmed, suffix: "" };
+}
+function normalizeConditionKey(key, mapField) {
+  const { field, suffix } = parseWhereKey(key);
+  const mapped = mapField(field);
+  return suffix ? `${mapped}${suffix}` : mapped;
+}
+function normalizeWhere(where, mapField) {
+  if (!where) return void 0;
+  if (Array.isArray(where)) {
+    return where.map(
+      (andGroup) => andGroup.map(
+        (condition) => Object.fromEntries(
+          Object.entries(condition).map(([key, value]) => [
+            normalizeConditionKey(key, mapField),
+            value
+          ])
+        )
+      )
+    );
+  }
+  return Object.fromEntries(
+    Object.entries(where).map(([key, value]) => [
+      normalizeConditionKey(key, mapField),
+      value
+    ])
+  );
+}
+function readReportMetadata(field) {
+  return field?._meta?.__report ?? field?.__report;
+}
+function isReportSystemField(fieldName, field) {
+  return REPORT_BASE_FIELDS.has(fieldName) || field?._meta?.__smrtSystemField || field?._meta?.__tenancy?.isTenantIdField;
+}
+async function buildReportDefinition(reportCtor) {
+  const options = getReportOptions(reportCtor);
+  const reportClassName = getRegisteredClassName(reportCtor);
+  const sourceName = sourceClassName(options.source);
+  const sourceTable = resolveTableName(sourceName);
+  const fields = await ObjectRegistry.getAllFields(reportClassName);
+  const reportFields = [];
+  for (const [fieldName, field] of fields.entries()) {
+    const report = readReportMetadata(field);
+    if (!report) {
+      if (!isReportSystemField(fieldName, field) && !field?.transient) {
+        throw new Error(
+          `Report field ${reportCtor.name}.${fieldName} is neither a grouping key nor an aggregate. Add @groupBy(), a time-bucket decorator, or an aggregate decorator.`
+        );
+      }
+      continue;
+    }
+    reportFields.push({
+      fieldName,
+      columnName: toSnakeCase(fieldName),
+      type: field.type,
+      report
+    });
+  }
+  return {
+    reportClassName,
+    sourceClassName: sourceName,
+    sourceTable,
+    fields: reportFields,
+    where: options.where,
+    having: options.having,
+    refresh: options.refresh
+  };
+}
+function sourceColumn(field) {
+  const report = field.report;
+  if (!report) {
+    throw new Error(`Report field ${field.fieldName} is missing metadata`);
+  }
+  if (report.kind === "group") {
+    return toSnakeCase(report.sourceColumn ?? field.fieldName);
+  }
+  if (report.kind === "bucket") {
+    return toSnakeCase(report.sourceColumn);
+  }
+  if (report.kind === "aggregate") {
+    if (!report.column) return "";
+    return toSnakeCase(report.column);
+  }
+  return "";
+}
+function getReportGroupingColumns(definition) {
+  const columns = definition.fields.filter(
+    (field) => field.report?.kind === "group" || field.report?.kind === "bucket"
+  ).map((field) => field.columnName ?? toSnakeCase(field.fieldName));
+  return columns.length > 0 ? columns : ["id"];
+}
+function compileReportDefinition(definition) {
+  const select = [];
+  const groupBy = [];
+  const reportFieldToColumn = /* @__PURE__ */ new Map();
+  for (const field of definition.fields) {
+    const outputColumn = field.columnName ?? toSnakeCase(field.fieldName);
+    reportFieldToColumn.set(field.fieldName, outputColumn);
+    reportFieldToColumn.set(outputColumn, outputColumn);
+    const report = field.report;
+    if (!report) continue;
+    if (report.kind === "group") {
+      select.push({
+        column: sourceColumn(field),
+        as: outputColumn
+      });
+      groupBy.push(outputColumn);
+      continue;
+    }
+    if (report.kind === "bucket") {
+      select.push({
+        bucket: report.unit,
+        column: sourceColumn(field),
+        as: outputColumn
+      });
+      groupBy.push(outputColumn);
+      continue;
+    }
+    select.push({
+      fn: report.fn,
+      column: report.column ? sourceColumn(field) : void 0,
+      as: outputColumn,
+      distinct: report.distinct
+    });
+  }
+  if (select.length === 0) {
+    throw new Error(
+      `${definition.reportClassName} has no report fields. Add @groupBy(), a time-bucket decorator, or an aggregate decorator.`
+    );
+  }
+  return {
+    from: definition.sourceTable,
+    select,
+    groupBy,
+    where: normalizeWhere(definition.where, (field) => toSnakeCase(field)),
+    having: normalizeWhere(
+      definition.having,
+      (field) => reportFieldToColumn.get(field) ?? toSnakeCase(field)
+    )
+  };
+}
+async function compileReportSpec(reportCtor) {
+  return compileReportDefinition(await buildReportDefinition(reportCtor));
+}
+export {
+  buildReportDefinition,
+  compileReportDefinition,
+  compileReportSpec,
+  getReportGroupingColumns
+};
+//# sourceMappingURL=compiler.js.map

package/dist/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sources":["../src/compiler.ts"],"sourcesContent":["import { ObjectRegistry, type SmrtObject } from '@happyvertical/smrt-core';\nimport { toSnakeCase } from '@happyvertical/smrt-core/utils';\nimport type { WhereClause } from '@happyvertical/sql';\nimport { getRuntimeReportOptions } from './decorators.js';\nimport type {\n  AggregateSelectExpr,\n  AggregateSpec,\n  ReportDefinition,\n  ReportFieldDefinition,\n  ReportFieldMetadata,\n  ReportOptions,\n  ReportSource,\n} from './types.js';\n\nconst REPORT_BASE_FIELDS = new Set([\n  'id',\n  'slug',\n  'context',\n  'created_at',\n  'updated_at',\n  'createdAt',\n  'updatedAt',\n  'refreshedAt',\n]);\n\nfunction isConstructor(\n  value: ReportSource,\n): value is new (\n  ...args: any[]\n) => SmrtObject {\n  return typeof value === 'function';\n}\n\nfunction sourceClassName(source: ReportSource): string {\n  if (typeof source === 'string') return source;\n  return source.name;\n}\n\nfunction reportOptionsFromRegistry(\n  reportCtor: new (...args: any[]) => SmrtObject,\n): ReportOptions | undefined {\n  const registered =\n    ObjectRegistry.getClassByConstructor(reportCtor) ??\n    ObjectRegistry.getClass(reportCtor.name);\n  return (registered?.config as { report?: ReportOptions } | undefined)?.report;\n}\n\nfunction getReportOptions(\n  reportCtor: new (...args: any[]) => SmrtObject,\n): ReportOptions {\n  const options =\n    getRuntimeReportOptions(reportCtor) ??\n    reportOptionsFromRegistry(reportCtor);\n  if (!options?.source) {\n    throw new Error(\n      `${reportCtor.name} is missing @report({ source }) metadata. ` +\n        `Decorate the report class with @report({ source: SourceClass }).`,\n    );\n  }\n  return options;\n}\n\nfunction getRegisteredClassName(\n  ctor: new (...args: any[]) => SmrtObject,\n): string {\n  const registered =\n    ObjectRegistry.getClassByConstructor(ctor) ??\n    ObjectRegistry.getClass(ctor.name);\n  return registered?.qualifiedName ?? registered?.name ?? ctor.name;\n}\n\nfunction resolveTableName(className: string): string {\n  const tableName = ObjectRegistry.getTableName(className);\n  if (!tableName) {\n    throw new Error(\n      `No SMRT table registered for ${className}. ` +\n        `Ensure the class is decorated with @smrt() and its manifest is loaded.`,\n    );\n  }\n  return tableName;\n}\n\nfunction parseWhereKey(key: string): { field: string; suffix: string } {\n  const trimmed = key.trim();\n  const operators = [\n    ' is not null',\n    ' is null',\n    ' not in',\n    ' like',\n    ' in',\n    ' !=',\n    ' >=',\n    ' <=',\n    ' >',\n    ' <',\n    ' =',\n  ];\n  const lower = trimmed.toLowerCase();\n  for (const operator of operators) {\n    if (lower.endsWith(operator)) {\n      return {\n        field: trimmed.slice(0, -operator.length).trim(),\n        suffix: operator,\n      };\n    }\n  }\n  return { field: trimmed, suffix: '' };\n}\n\nfunction normalizeConditionKey(\n  key: string,\n  mapField: (field: string) => string,\n): string {\n  const { field, suffix } = parseWhereKey(key);\n  const mapped = mapField(field);\n  return suffix ? `${mapped}${suffix}` : mapped;\n}\n\nfunction normalizeWhere(\n  where: WhereClause | undefined,\n  mapField: (field: string) => string,\n): WhereClause | undefined {\n  if (!where) return undefined;\n\n  if (Array.isArray(where)) {\n    return where.map((andGroup) =>\n      andGroup.map((condition: Record<string, any>) =>\n        Object.fromEntries(\n          Object.entries(condition).map(([key, value]) => [\n            normalizeConditionKey(key, mapField),\n            value,\n          ]),\n        ),\n      ),\n    );\n  }\n\n  return Object.fromEntries(\n    Object.entries(where).map(([key, value]) => [\n      normalizeConditionKey(key, mapField),\n      value,\n    ]),\n  );\n}\n\nfunction readReportMetadata(field: any): ReportFieldMetadata | undefined {\n  return field?._meta?.__report ?? field?.__report;\n}\n\nfunction isReportSystemField(fieldName: string, field: any): boolean {\n  return (\n    REPORT_BASE_FIELDS.has(fieldName) ||\n    field?._meta?.__smrtSystemField ||\n    field?._meta?.__tenancy?.isTenantIdField\n  );\n}\n\nexport async function buildReportDefinition(\n  reportCtor: new (...args: any[]) => SmrtObject,\n): Promise<ReportDefinition> {\n  const options = getReportOptions(reportCtor);\n  const reportClassName = getRegisteredClassName(reportCtor);\n  const sourceName = sourceClassName(options.source);\n  const sourceTable = resolveTableName(sourceName);\n  const fields = await ObjectRegistry.getAllFields(reportClassName);\n\n  const reportFields: ReportFieldDefinition[] = [];\n  for (const [fieldName, field] of fields.entries()) {\n    const report = readReportMetadata(field);\n    if (!report) {\n      if (!isReportSystemField(fieldName, field) && !field?.transient) {\n        throw new Error(\n          `Report field ${reportCtor.name}.${fieldName} is neither a grouping key nor an aggregate. ` +\n            `Add @groupBy(), a time-bucket decorator, or an aggregate decorator.`,\n        );\n      }\n      continue;\n    }\n\n    reportFields.push({\n      fieldName,\n      columnName: toSnakeCase(fieldName),\n      type: field.type,\n      report,\n    });\n  }\n\n  return {\n    reportClassName,\n    sourceClassName: sourceName,\n    sourceTable,\n    fields: reportFields,\n    where: options.where,\n    having: options.having,\n    refresh: options.refresh,\n  };\n}\n\nfunction sourceColumn(field: ReportFieldDefinition): string {\n  const report = field.report;\n  if (!report) {\n    throw new Error(`Report field ${field.fieldName} is missing metadata`);\n  }\n  if (report.kind === 'group') {\n    return toSnakeCase(report.sourceColumn ?? field.fieldName);\n  }\n  if (report.kind === 'bucket') {\n    return toSnakeCase(report.sourceColumn);\n  }\n  if (report.kind === 'aggregate') {\n    if (!report.column) return '';\n    return toSnakeCase(report.column);\n  }\n  return '';\n}\n\nexport function getReportGroupingColumns(\n  definition: Pick<ReportDefinition, 'fields'>,\n): string[] {\n  const columns = definition.fields\n    .filter(\n      (field) =>\n        field.report?.kind === 'group' || field.report?.kind === 'bucket',\n    )\n    .map((field) => field.columnName ?? toSnakeCase(field.fieldName));\n  return columns.length > 0 ? columns : ['id'];\n}\n\nexport function compileReportDefinition(\n  definition: ReportDefinition,\n): AggregateSpec {\n  const select: AggregateSelectExpr[] = [];\n  const groupBy: string[] = [];\n  const reportFieldToColumn = new Map<string, string>();\n\n  for (const field of definition.fields) {\n    const outputColumn = field.columnName ?? toSnakeCase(field.fieldName);\n    reportFieldToColumn.set(field.fieldName, outputColumn);\n    reportFieldToColumn.set(outputColumn, outputColumn);\n\n    const report = field.report;\n    if (!report) continue;\n\n    if (report.kind === 'group') {\n      select.push({\n        column: sourceColumn(field),\n        as: outputColumn,\n      });\n      groupBy.push(outputColumn);\n      continue;\n    }\n\n    if (report.kind === 'bucket') {\n      select.push({\n        bucket: report.unit,\n        column: sourceColumn(field),\n        as: outputColumn,\n      });\n      groupBy.push(outputColumn);\n      continue;\n    }\n\n    select.push({\n      fn: report.fn,\n      column: report.column ? sourceColumn(field) : undefined,\n      as: outputColumn,\n      distinct: report.distinct,\n    });\n  }\n\n  if (select.length === 0) {\n    throw new Error(\n      `${definition.reportClassName} has no report fields. ` +\n        `Add @groupBy(), a time-bucket decorator, or an aggregate decorator.`,\n    );\n  }\n\n  return {\n    from: definition.sourceTable,\n    select,\n    groupBy,\n    where: normalizeWhere(definition.where, (field) => toSnakeCase(field)),\n    having: normalizeWhere(\n      definition.having,\n      (field) => reportFieldToColumn.get(field) ?? toSnakeCase(field),\n    ),\n  };\n}\n\nexport async function compileReportSpec(\n  reportCtor: new (...args: any[]) => SmrtObject,\n): Promise<AggregateSpec> {\n  return compileReportDefinition(await buildReportDefinition(reportCtor));\n}\n"],"names":[],"mappings":"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"}

package/dist/decorators.d.ts

@@ -0,0 +1,90 @@
+import { AggregateFunction } from '@happyvertical/sql';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { WhereClause } from '@happyvertical/sql';
+
+export declare function aggregate(options: AggregateDecoratorOptions): PropertyDecorator;
+
+export declare interface AggregateDecoratorOptions {
+    fn: ReportAggregateFn;
+    column?: string;
+    distinct?: boolean;
+}
+
+export declare const avg: (column?: string, options?: {
+    distinct?: boolean;
+}) => PropertyDecorator;
+
+export declare function count(): PropertyDecorator;
+
+export declare function count(column: string, options?: {
+    distinct?: boolean;
+}): PropertyDecorator;
+
+export declare function count(options: {
+    distinct?: boolean;
+}): PropertyDecorator;
+
+export declare const day: (sourceColumn: string) => PropertyDecorator;
+
+export declare function getRuntimeReportOptions(ctor: Function): ReportOptions | undefined;
+
+export declare function groupBy(sourceColumn?: string): PropertyDecorator;
+
+export declare const hour: (sourceColumn: string) => PropertyDecorator;
+
+export declare const max: (column?: string, options?: {
+    distinct?: boolean;
+}) => PropertyDecorator;
+
+export declare const min: (column?: string, options?: {
+    distinct?: boolean;
+}) => PropertyDecorator;
+
+export declare const minute: (sourceColumn: string) => PropertyDecorator;
+
+export declare const month: (sourceColumn: string) => PropertyDecorator;
+
+export declare const quarter: (sourceColumn: string) => PropertyDecorator;
+
+export declare function report(options: ReportOptions): <T extends abstract new (...args: any[]) => any>(ctor: T) => T;
+
+declare type ReportAggregateFn = AggregateFunction;
+
+declare interface ReportOptions {
+    source: ReportSource;
+    where?: WhereClause;
+    having?: WhereClause;
+    refresh?: ReportRefreshConfig;
+}
+
+declare interface ReportRefreshConfig {
+    mode?: ReportRefreshMode;
+    schedule?: string;
+    onChange?: ReportSource[];
+    /**
+     * Milliseconds before collection reads trigger a synchronous refresh.
+     *
+     * TTL refresh checks add a read-time MAX(refreshedAt) query, and stale reads
+     * perform the refresh before returning list/get results.
+     */
+    ttl?: number;
+    manual?: boolean;
+    watermarkColumn?: string;
+    softDeleteColumn?: string;
+    fullRebuildSchedule?: string;
+    tenantFanout?: boolean;
+}
+
+declare type ReportRefreshMode = 'rebuild' | 'incremental';
+
+declare type ReportSource = string | (new (...args: any[]) => SmrtObject) | (abstract new (...args: any[]) => SmrtObject);
+
+export declare const sum: (column?: string, options?: {
+    distinct?: boolean;
+}) => PropertyDecorator;
+
+export declare const week: (sourceColumn: string) => PropertyDecorator;
+
+export declare const year: (sourceColumn: string) => PropertyDecorator;
+
+export { }

package/dist/decorators.js

@@ -0,0 +1,84 @@
+import { registerCompatibleFieldDecorator, ObjectRegistry } from "@happyvertical/smrt-core";
+const reportOptionsByConstructor = /* @__PURE__ */ new WeakMap();
+function report(options) {
+  return (ctor) => {
+    reportOptionsByConstructor.set(ctor, options);
+    return ctor;
+  };
+}
+function getRuntimeReportOptions(ctor) {
+  return reportOptionsByConstructor.get(ctor);
+}
+function registerReportField(metadata) {
+  return ((targetOrValue, propertyKeyOrContext) => {
+    registerCompatibleFieldDecorator(
+      targetOrValue,
+      propertyKeyOrContext,
+      (className, propertyKey) => {
+        ObjectRegistry.registerFieldDecorator(className, propertyKey, {
+          __report: metadata
+        });
+      }
+    );
+  });
+}
+function groupBy(sourceColumn) {
+  return registerReportField({ kind: "group", sourceColumn });
+}
+function bucket(unit, sourceColumn) {
+  return registerReportField({
+    kind: "bucket",
+    unit,
+    sourceColumn
+  });
+}
+const minute = (sourceColumn) => bucket("minute", sourceColumn);
+const hour = (sourceColumn) => bucket("hour", sourceColumn);
+const day = (sourceColumn) => bucket("day", sourceColumn);
+const week = (sourceColumn) => bucket("week", sourceColumn);
+const month = (sourceColumn) => bucket("month", sourceColumn);
+const quarter = (sourceColumn) => bucket("quarter", sourceColumn);
+const year = (sourceColumn) => bucket("year", sourceColumn);
+function aggregate(options) {
+  return registerReportField({
+    kind: "aggregate",
+    fn: options.fn,
+    column: options.column,
+    distinct: options.distinct
+  });
+}
+function aggregateDecorator(fn) {
+  return (column, options = {}) => aggregate({ fn, column, distinct: options.distinct });
+}
+const sum = aggregateDecorator("sum");
+const avg = aggregateDecorator("avg");
+const min = aggregateDecorator("min");
+const max = aggregateDecorator("max");
+function count(columnOrOptions, options = {}) {
+  const column = typeof columnOrOptions === "string" ? columnOrOptions : void 0;
+  const resolvedOptions = typeof columnOrOptions === "object" ? columnOrOptions : options;
+  return aggregate({
+    fn: "count",
+    column,
+    distinct: resolvedOptions.distinct
+  });
+}
+export {
+  aggregate,
+  avg,
+  count,
+  day,
+  getRuntimeReportOptions,
+  groupBy,
+  hour,
+  max,
+  min,
+  minute,
+  month,
+  quarter,
+  report,
+  sum,
+  week,
+  year
+};
+//# sourceMappingURL=decorators.js.map

package/dist/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sources":["../src/decorators.ts"],"sourcesContent":["import {\n  ObjectRegistry,\n  registerCompatibleFieldDecorator,\n} from '@happyvertical/smrt-core';\nimport type {\n  ReportAggregateFieldMetadata,\n  ReportAggregateFn,\n  ReportBucketFieldMetadata,\n  ReportFieldMetadata,\n  ReportOptions,\n  ReportTimeBucketUnit,\n} from './types.js';\n\nconst reportOptionsByConstructor = new WeakMap<Function, ReportOptions>();\n\nexport function report(options: ReportOptions) {\n  return <T extends abstract new (...args: any[]) => any>(ctor: T): T => {\n    reportOptionsByConstructor.set(ctor, options);\n    return ctor;\n  };\n}\n\nexport function getRuntimeReportOptions(\n  ctor: Function,\n): ReportOptions | undefined {\n  return reportOptionsByConstructor.get(ctor);\n}\n\nfunction registerReportField(metadata: ReportFieldMetadata) {\n  return ((targetOrValue: any, propertyKeyOrContext: any) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          __report: metadata,\n        });\n      },\n    );\n  }) as PropertyDecorator;\n}\n\nexport function groupBy(sourceColumn?: string): PropertyDecorator {\n  return registerReportField({ kind: 'group', sourceColumn });\n}\n\nfunction bucket(\n  unit: ReportTimeBucketUnit,\n  sourceColumn: string,\n): PropertyDecorator {\n  return registerReportField({\n    kind: 'bucket',\n    unit,\n    sourceColumn,\n  } satisfies ReportBucketFieldMetadata);\n}\n\nexport const minute = (sourceColumn: string) => bucket('minute', sourceColumn);\nexport const hour = (sourceColumn: string) => bucket('hour', sourceColumn);\nexport const day = (sourceColumn: string) => bucket('day', sourceColumn);\nexport const week = (sourceColumn: string) => bucket('week', sourceColumn);\nexport const month = (sourceColumn: string) => bucket('month', sourceColumn);\nexport const quarter = (sourceColumn: string) =>\n  bucket('quarter', sourceColumn);\nexport const year = (sourceColumn: string) => bucket('year', sourceColumn);\n\nexport interface AggregateDecoratorOptions {\n  fn: ReportAggregateFn;\n  column?: string;\n  distinct?: boolean;\n}\n\nexport function aggregate(\n  options: AggregateDecoratorOptions,\n): PropertyDecorator {\n  return registerReportField({\n    kind: 'aggregate',\n    fn: options.fn,\n    column: options.column,\n    distinct: options.distinct,\n  } satisfies ReportAggregateFieldMetadata);\n}\n\nfunction aggregateDecorator(fn: ReportAggregateFn) {\n  return (column?: string, options: { distinct?: boolean } = {}) =>\n    aggregate({ fn, column, distinct: options.distinct });\n}\n\nexport const sum = aggregateDecorator('sum');\nexport const avg = aggregateDecorator('avg');\nexport const min = aggregateDecorator('min');\nexport const max = aggregateDecorator('max');\n\nexport function count(): PropertyDecorator;\nexport function count(\n  column: string,\n  options?: { distinct?: boolean },\n): PropertyDecorator;\nexport function count(options: { distinct?: boolean }): PropertyDecorator;\nexport function count(\n  columnOrOptions?: string | { distinct?: boolean },\n  options: { distinct?: boolean } = {},\n): PropertyDecorator {\n  const column =\n    typeof columnOrOptions === 'string' ? columnOrOptions : undefined;\n  const resolvedOptions =\n    typeof columnOrOptions === 'object' ? columnOrOptions : options;\n  return aggregate({\n    fn: 'count',\n    column,\n    distinct: resolvedOptions.distinct,\n  });\n}\n"],"names":[],"mappings":";AAaA,MAAM,iDAAiC,QAAA;AAEhC,SAAS,OAAO,SAAwB;AAC7C,SAAO,CAAiD,SAAe;AACrE,+BAA2B,IAAI,MAAM,OAAO;AAC5C,WAAO;AAAA,EACT;AACF;AAEO,SAAS,wBACd,MAC2B;AAC3B,SAAO,2BAA2B,IAAI,IAAI;AAC5C;AAEA,SAAS,oBAAoB,UAA+B;AAC1D,UAAQ,CAAC,eAAoB,yBAA8B;AACzD;AAAA,MACE;AAAA,MACA;AAAA,MACA,CAAC,WAAW,gBAAgB;AAC1B,uBAAe,uBAAuB,WAAW,aAAa;AAAA,UAC5D,UAAU;AAAA,QAAA,CACX;AAAA,MACH;AAAA,IAAA;AAAA,EAEJ;AACF;AAEO,SAAS,QAAQ,cAA0C;AAChE,SAAO,oBAAoB,EAAE,MAAM,SAAS,cAAc;AAC5D;AAEA,SAAS,OACP,MACA,cACmB;AACnB,SAAO,oBAAoB;AAAA,IACzB,MAAM;AAAA,IACN;AAAA,IACA;AAAA,EAAA,CACmC;AACvC;AAEO,MAAM,SAAS,CAAC,iBAAyB,OAAO,UAAU,YAAY;AACtE,MAAM,OAAO,CAAC,iBAAyB,OAAO,QAAQ,YAAY;AAClE,MAAM,MAAM,CAAC,iBAAyB,OAAO,OAAO,YAAY;AAChE,MAAM,OAAO,CAAC,iBAAyB,OAAO,QAAQ,YAAY;AAClE,MAAM,QAAQ,CAAC,iBAAyB,OAAO,SAAS,YAAY;AACpE,MAAM,UAAU,CAAC,iBACtB,OAAO,WAAW,YAAY;AACzB,MAAM,OAAO,CAAC,iBAAyB,OAAO,QAAQ,YAAY;AAQlE,SAAS,UACd,SACmB;AACnB,SAAO,oBAAoB;AAAA,IACzB,MAAM;AAAA,IACN,IAAI,QAAQ;AAAA,IACZ,QAAQ,QAAQ;AAAA,IAChB,UAAU,QAAQ;AAAA,EAAA,CACoB;AAC1C;AAEA,SAAS,mBAAmB,IAAuB;AACjD,SAAO,CAAC,QAAiB,UAAkC,CAAA,MACzD,UAAU,EAAE,IAAI,QAAQ,UAAU,QAAQ,SAAA,CAAU;AACxD;AAEO,MAAM,MAAM,mBAAmB,KAAK;AACpC,MAAM,MAAM,mBAAmB,KAAK;AACpC,MAAM,MAAM,mBAAmB,KAAK;AACpC,MAAM,MAAM,mBAAmB,KAAK;AAQpC,SAAS,MACd,iBACA,UAAkC,IACf;AACnB,QAAM,SACJ,OAAO,oBAAoB,WAAW,kBAAkB;AAC1D,QAAM,kBACJ,OAAO,oBAAoB,WAAW,kBAAkB;AAC1D,SAAO,UAAU;AAAA,IACf,IAAI;AAAA,IACJ;AAAA,IACA,UAAU,gBAAgB;AAAA,EAAA,CAC3B;AACH;"}