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/README.md +175 -28
- package/dist/analytics.d.ts +47 -4
- package/dist/dataset.d.ts +50 -30
- package/dist/handler.d.ts +56 -0
- package/dist/handler.js +49 -0
- package/dist/index-g255jb1s.js +149 -0
- package/dist/index-g2mjqx4f.js +303 -0
- package/dist/{index-wrr67sxq.js → index-zgb1e89d.js} +160 -451
- package/dist/index.d.ts +1 -1
- package/dist/index.js +7 -5
- package/dist/period.d.ts +5 -0
- package/dist/shapes.d.ts +111 -0
- package/dist/shapes.js +134 -0
- package/dist/testing.d.ts +9 -4
- package/dist/testing.js +13 -3
- package/package.json +14 -2
- package/src/analytics.ts +337 -40
- package/src/dataset.ts +135 -60
- package/src/handler.ts +124 -0
- package/src/index.ts +3 -0
- package/src/period.ts +32 -0
- package/src/plan.ts +6 -0
- package/src/shapes.ts +295 -0
- package/src/testing.ts +31 -9
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 {
|
|
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
|
|
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
|
-
/**
|
|
28
|
-
|
|
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,
|
|
51
|
-
*
|
|
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:
|
|
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:
|
|
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:
|
|
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) {
|