measurr 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/shapes.ts ADDED
@@ -0,0 +1,295 @@
1
+ /**
2
+ * Chart-ready shapes of a query result: a KPI, a time series, a distribution, a pivot and a
3
+ * leaderboard. Pure functions over `analytics.query` results, with the previous period when the
4
+ * query compared with it. They add no numbers the result does not hold.
5
+ */
6
+ import { bucketStarts } from './period.js'
7
+ import type { ResultPeriod } from './query.js'
8
+
9
+ type DimensionValue = { key: string | number | null; label: string }
10
+ type Measures = Record<string, number | null>
11
+
12
+ /** Any `analytics.query` result. */
13
+ type AnyResult = {
14
+ period: ResultPeriod
15
+ rows: readonly Record<string, unknown>[]
16
+ totals: Measures
17
+ previous?: {
18
+ period: ResultPeriod
19
+ rows: readonly Record<string, unknown>[]
20
+ totals: Measures
21
+ }
22
+ truncated: boolean
23
+ }
24
+
25
+ type MeasureOf<R extends AnyResult> = keyof R['totals'] & string
26
+ type DimensionOf<R extends AnyResult> = Exclude<
27
+ keyof R['rows'][number] & string,
28
+ MeasureOf<R>
29
+ >
30
+
31
+ export type KpiShape = {
32
+ kind: 'kpi'
33
+ value: number | null
34
+ /** Only when the query compared with the previous period. */
35
+ previous?: number | null
36
+ /** `(value - previous) / |previous|`; null when either is null or previous is 0. */
37
+ change?: number | null
38
+ }
39
+
40
+ export type SeriesPoint = {
41
+ /** The bucket's start date, `YYYY-MM-DD`. */
42
+ bucket: string
43
+ value: number | null
44
+ }
45
+
46
+ export type TimeseriesShape = {
47
+ kind: 'timeseries'
48
+ unit: 'day' | 'week' | 'month'
49
+ series: {
50
+ key: string | number | null
51
+ label: string
52
+ points: SeriesPoint[]
53
+ /** The previous period's points, its own buckets; compare them by position. */
54
+ previous?: SeriesPoint[]
55
+ }[]
56
+ truncated: boolean
57
+ }
58
+
59
+ export type DistributionShape = {
60
+ kind: 'distribution'
61
+ /** The measure over every row, so a many-to-many split can add up to more. */
62
+ total: number | null
63
+ segments: (DimensionValue & {
64
+ value: number | null
65
+ /** `value / total`, 0-1. */
66
+ share: number | null
67
+ previous?: number | null
68
+ })[]
69
+ truncated: boolean
70
+ }
71
+
72
+ export type PivotShape = {
73
+ kind: 'pivot'
74
+ rows: DimensionValue[]
75
+ columns: DimensionValue[]
76
+ /** `values[row][column]`. */
77
+ values: (number | null)[][]
78
+ total: number | null
79
+ truncated: boolean
80
+ }
81
+
82
+ export type LeaderboardShape = {
83
+ kind: 'leaderboard'
84
+ items: (DimensionValue & {
85
+ rank: number
86
+ value: number | null
87
+ /** Every measure the query asked for. */
88
+ values: Measures
89
+ })[]
90
+ truncated: boolean
91
+ }
92
+
93
+ export function toKpi<R extends AnyResult>(
94
+ result: R,
95
+ measure: MeasureOf<R>
96
+ ): KpiShape {
97
+ const value = result.totals[measure] ?? null
98
+ if (!result.previous) return { kind: 'kpi', value }
99
+
100
+ const previous = result.previous.totals[measure] ?? null
101
+ const change =
102
+ value === null || previous === null || previous === 0
103
+ ? null
104
+ : (value - previous) / Math.abs(previous)
105
+
106
+ return { kind: 'kpi', value, previous, change }
107
+ }
108
+
109
+ /**
110
+ * One series per value of `series` (or one series named after the measure), with a point for
111
+ * every bucket of the period: buckets without rows get `fill` (0 by default; pass null for
112
+ * averages). Series come in the order they first appear in the rows. Group by the bucket
113
+ * dimension and set a `limit` that covers every bucket and series, or the result is truncated.
114
+ */
115
+ export function toTimeseries<R extends AnyResult>(
116
+ result: R,
117
+ options: {
118
+ bucket: DimensionOf<R>
119
+ unit: 'day' | 'week' | 'month'
120
+ measure: MeasureOf<R>
121
+ series?: DimensionOf<R>
122
+ fill?: number | null
123
+ }
124
+ ): TimeseriesShape {
125
+ const { bucket, unit, measure, series } = options
126
+ const fill = options.fill === undefined ? 0 : options.fill
127
+ const seriesOf = (row: Record<string, unknown>) =>
128
+ series ? dimensionValue(row, series) : { key: measure, label: measure }
129
+
130
+ const pointsOf = (
131
+ period: ResultPeriod,
132
+ rows: readonly Record<string, unknown>[],
133
+ key: string | number | null
134
+ ): SeriesPoint[] => {
135
+ const values = new Map<string, number | null>()
136
+ for (const row of rows) {
137
+ const start = dimensionValue(row, bucket).key
138
+ if (start === null || seriesOf(row).key !== key) continue
139
+ values.set(String(start), measureValue(row, measure))
140
+ }
141
+ const starts =
142
+ 'all' in period
143
+ ? [...values.keys()].sort()
144
+ : bucketStarts(period.from, period.to, unit)
145
+ return starts.map((start) => ({
146
+ bucket: start,
147
+ value: values.has(start) ? (values.get(start) ?? null) : fill
148
+ }))
149
+ }
150
+
151
+ const { previous } = result
152
+ return {
153
+ kind: 'timeseries',
154
+ unit,
155
+ series: distinct(result.rows.map(seriesOf)).map(({ key, label }) => ({
156
+ key,
157
+ label,
158
+ points: pointsOf(result.period, result.rows, key),
159
+ ...(previous && {
160
+ previous: pointsOf(previous.period, previous.rows, key)
161
+ })
162
+ })),
163
+ truncated: result.truncated
164
+ }
165
+ }
166
+
167
+ export function toDistribution<R extends AnyResult>(
168
+ result: R,
169
+ options: { by: DimensionOf<R>; measure: MeasureOf<R> }
170
+ ): DistributionShape {
171
+ const { by, measure } = options
172
+ const total = result.totals[measure] ?? null
173
+ const previous =
174
+ result.previous &&
175
+ new Map(
176
+ result.previous.rows.map((row) => [
177
+ dimensionValue(row, by).key,
178
+ measureValue(row, measure)
179
+ ])
180
+ )
181
+
182
+ return {
183
+ kind: 'distribution',
184
+ total,
185
+ segments: result.rows.map((row) => {
186
+ const { key, label } = dimensionValue(row, by)
187
+ const value = measureValue(row, measure)
188
+ return {
189
+ key,
190
+ label,
191
+ value,
192
+ share: value === null || !total ? null : value / total,
193
+ ...(previous && { previous: previous.get(key) ?? null })
194
+ }
195
+ }),
196
+ truncated: result.truncated
197
+ }
198
+ }
199
+
200
+ /**
201
+ * A grid of `measure` by two grouped dimensions. Numeric keys (weekdays, hours) are sorted;
202
+ * other keys keep the order they first appear in. Cells without a row get `fill` (0 by
203
+ * default; pass null for averages).
204
+ */
205
+ export function toPivot<R extends AnyResult>(
206
+ result: R,
207
+ options: {
208
+ rows: DimensionOf<R>
209
+ columns: DimensionOf<R>
210
+ measure: MeasureOf<R>
211
+ fill?: number | null
212
+ }
213
+ ): PivotShape {
214
+ const fill = options.fill === undefined ? 0 : options.fill
215
+ const rowsOf = (dimension: string) =>
216
+ sortNumeric(
217
+ distinct(result.rows.map((row) => dimensionValue(row, dimension)))
218
+ )
219
+ const rows = rowsOf(options.rows)
220
+ const columns = rowsOf(options.columns)
221
+ const values = rows.map(() => columns.map(() => fill))
222
+
223
+ for (const row of result.rows) {
224
+ const r = rows.findIndex(
225
+ (entry) => entry.key === dimensionValue(row, options.rows).key
226
+ )
227
+ const c = columns.findIndex(
228
+ (entry) => entry.key === dimensionValue(row, options.columns).key
229
+ )
230
+ const cells = values[r]
231
+ if (cells) cells[c] = measureValue(row, options.measure)
232
+ }
233
+
234
+ return {
235
+ kind: 'pivot',
236
+ rows,
237
+ columns,
238
+ values,
239
+ total: result.totals[options.measure] ?? null,
240
+ truncated: result.truncated
241
+ }
242
+ }
243
+
244
+ /** The rows in query order (sort the query by `measure`), ranked from 1. */
245
+ export function toLeaderboard<R extends AnyResult>(
246
+ result: R,
247
+ options: { by: DimensionOf<R>; measure: MeasureOf<R> }
248
+ ): LeaderboardShape {
249
+ const measures = Object.keys(result.totals)
250
+
251
+ return {
252
+ kind: 'leaderboard',
253
+ items: result.rows.map((row, index) => ({
254
+ ...dimensionValue(row, options.by),
255
+ rank: index + 1,
256
+ value: measureValue(row, options.measure),
257
+ values: Object.fromEntries(
258
+ measures.map((key) => [key, measureValue(row, key)])
259
+ )
260
+ })),
261
+ truncated: result.truncated
262
+ }
263
+ }
264
+
265
+ function dimensionValue(
266
+ row: Record<string, unknown>,
267
+ key: string
268
+ ): DimensionValue {
269
+ const value = row[key]
270
+ if (typeof value === 'object' && value !== null && 'label' in value) {
271
+ return value as DimensionValue
272
+ }
273
+ throw new Error(`The rows are not grouped by ${key}`)
274
+ }
275
+
276
+ function measureValue(row: Record<string, unknown>, key: string) {
277
+ const value = row[key]
278
+ return typeof value === 'number' ? value : null
279
+ }
280
+
281
+ /** The values by key, first one first. */
282
+ function distinct(values: DimensionValue[]): DimensionValue[] {
283
+ const byKey = new Map<string | number | null, DimensionValue>()
284
+ for (const value of values) {
285
+ if (!byKey.has(value.key))
286
+ byKey.set(value.key, { key: value.key, label: value.label })
287
+ }
288
+ return [...byKey.values()]
289
+ }
290
+
291
+ function sortNumeric(values: DimensionValue[]): DimensionValue[] {
292
+ return values.every((value) => typeof value.key === 'number')
293
+ ? [...values].sort((a, b) => Number(a.key) - Number(b.key))
294
+ : values
295
+ }
package/src/testing.ts CHANGED
@@ -3,7 +3,11 @@
3
3
  * Framework-free: `checkDatasetContract` returns a report and `assertDatasetContract` throws
4
4
  * with every failure listed, so it works from `bun:test`, vitest or a script.
5
5
  */
6
- import { type AnalyticsSource, createAnalytics } from './analytics.js'
6
+ import {
7
+ type AnalyticsSource,
8
+ createAnalytics,
9
+ isAnalyticsError
10
+ } from './analytics.js'
7
11
  import {
8
12
  type AnyDataset,
9
13
  type AnyDimension,
@@ -11,7 +15,7 @@ import {
11
15
  measure
12
16
  } from './dataset.js'
13
17
  import type { PeriodInput } from './period.js'
14
- import type { TenantId } from './plan.js'
18
+ import { type Tenant, type TenantId, allTenants } from './plan.js'
15
19
  import { MAX_MEASURES } from './query.js'
16
20
 
17
21
  export type ContractCheck = {
@@ -24,8 +28,11 @@ export type ContractReport = { ok: boolean; checks: ContractCheck[] }
24
28
  export type ContractOptions = {
25
29
  dataset: AnyDataset
26
30
  source: AnalyticsSource
27
- /** A tenant with seeded rows in the period. */
28
- tenant: string | number
31
+ /**
32
+ * A tenant with seeded rows in the period. `allTenants` for a dataset without a tenant
33
+ * column, which no single tenant may query.
34
+ */
35
+ tenant: TenantId | typeof allTenants
29
36
  /** A tenant with no rows; defaults to a sentinel that no real tenant uses. */
30
37
  emptyTenant?: string | number
31
38
  /** A timezone far from UTC makes bucketing mistakes visible. Defaults to Pacific/Auckland. */
@@ -47,8 +54,9 @@ type ProbeResult = {
47
54
 
48
55
  /**
49
56
  * Checks that every measure, grouping and filter compiles and runs, that groups add up to the
50
- * total, that labels resolve, that another tenant's rows never count, and that day buckets
51
- * agree with periods in the timezone.
57
+ * total, that labels resolve, that another tenant's rows never count (or, for a dataset
58
+ * without a tenant column, that a scoped caller is refused), and that day buckets agree with
59
+ * periods in the timezone. Fields marked with `access` are checked like any other.
52
60
  */
53
61
  export async function checkDatasetContract(
54
62
  options: ContractOptions
@@ -79,14 +87,15 @@ export async function checkDatasetContract(
79
87
  const analytics = createAnalytics({
80
88
  datasets: [probe],
81
89
  sources: { main: options.source },
82
- tenant: (ctx: { tenant: TenantId | readonly TenantId[] }) => ctx.tenant,
90
+ tenant: (ctx: { tenant: Tenant }) => ctx.tenant,
91
+ authorizeField: () => true,
83
92
  timezone: () => timezone,
84
93
  ...(options.now && { now: options.now })
85
94
  })
86
95
 
87
96
  const run = async (
88
97
  query: Record<string, unknown>,
89
- tenant: TenantId | readonly TenantId[] = options.tenant
98
+ tenant: Tenant = options.tenant
90
99
  ): Promise<ProbeResult> => {
91
100
  const input = { dataset: dataset.key, period, limit: 100, ...query }
92
101
  return (await analytics.query(input as never, {
@@ -113,10 +122,12 @@ export async function checkDatasetContract(
113
122
 
114
123
  const total = (await run({ measures: [COUNT] })).totals[COUNT] ?? 0
115
124
  if (total === 0) {
125
+ const scope =
126
+ options.tenant === allTenants ? 'The dataset' : `Tenant ${options.tenant}`
116
127
  checks.push({
117
128
  name: 'seeded rows',
118
129
  ok: false,
119
- message: `Tenant ${options.tenant} has no rows in the period; the checks below prove little`
130
+ message: `${scope} has no rows in the period; the checks below prove little`
120
131
  })
121
132
  }
122
133
 
@@ -211,6 +222,17 @@ export async function checkDatasetContract(
211
222
  ['an empty tenant list', []]
212
223
  ] as const) {
213
224
  await check(`tenant isolation: ${name}`, async () => {
225
+ // Rows without a tenant cannot be isolated; a scoped caller must be refused instead.
226
+ if (!dataset.tenantColumn) {
227
+ const refused = await run({ measures: [COUNT] }, tenant).then(
228
+ () => false,
229
+ (error: unknown) => isAnalyticsError(error, 'forbidden')
230
+ )
231
+ return refused
232
+ ? undefined
233
+ : `${name} may query a dataset without a tenant column`
234
+ }
235
+
214
236
  const measures = Object.keys(probe.measures)
215
237
  const leaked: [string, number | null][] = []
216
238
  for (let start = 0; start < measures.length; start += MAX_MEASURES) {