measurr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristoffer Hansen
+
+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/README.md

@@ -0,0 +1,340 @@
+# measurr
+
+A small, typed semantic layer. You declare **datasets** (one fact table each) with
+**measures** and **dimensions**; callers (people, charts, an LLM tool) send a small JSON
+query; the engine compiles it to SQL for your database, runs it through your driver and
+returns shaped, typed rows.
+
+- No SQL text in definitions: datasets are built from typed expression builders, so a
+  renamed column, `avg` over a string or `between` on an enum fails typecheck.
+- Database-neutral definitions: dialects plug in through the `Dialect` interface, and Postgres
+  ships today (`measurr/postgres`).
+- Tenant-scoped by construction: the engine adds the tenant filter to every statement and
+  refuses to run without a tenant.
+- The query schema is generated with Zod, so it doubles as an LLM tool schema
+  (`z.toJSONSchema`) and as the request validator. It can be built per caller, offering only
+  the datasets they may query.
+- No driver or ORM dependency. `zod` is a peer dependency.
+
+## Quick start
+
+```ts
+import {
+	caseWhen, createAnalytics, defineDataset, dimension, eq, exists, gte, measure, table
+} from 'measurr'
+import { postgresDialect } from 'measurr/postgres'
+
+// Row types are plain TypeScript types (Prisma models work as they are).
+const order = table<Order>('orders')
+
+// A join declares its ON clause once. Any expression that reads `region` brings the join
+// with it; the planner adds it only when a query uses such an expression.
+const region = order.leftJoin(table<Region>('regions'), (r) =>
+	eq(r.col('id'), order.col('regionId'))
+)
+
+// A many-to-many link is a standalone table plus its link condition.
+const orderTag = table<OrderTag>('order_tags')
+const tag = orderTag.leftJoin(table<Tag>('tags'), (t) => eq(t.col('id'), orderTag.col('tagId')))
+const refund = table<Refund>('refunds')
+
+export const orders = defineDataset({
+	key: 'orders',
+	label: 'Orders',
+	description: 'One row per order. Test orders are excluded.',
+	from: order,
+	tenantColumn: order.col('tenantId'),
+	scope: eq(order.col('isTest'), false),
+	time: { created: { column: order.col('createdAt'), label: 'Created' } },
+	measures: {
+		orders: measure.count({ label: 'Orders' }),
+		revenue: measure.sum(order.col('amount'), { label: 'Revenue' }),
+		refunded: measure.countWhere(exists(refund, eq(refund.col('orderId'), order.col('id'))), {
+			label: 'Refunded orders'
+		}),
+		paidShare: measure.share({ label: 'Paid', numerator: eq(order.col('status'), 'PAID') }),
+		refundRate: measure.ratio('refunded', 'orders', { label: 'Refund rate' })
+	},
+	dimensions: {
+		status: dimension.enum(order.col('status'), OrderStatus, {
+			label: 'Status',
+			labels: { OPEN: 'Open', PAID: 'Paid', REFUNDED: 'Refunded' }
+		}),
+		region: dimension.relation({
+			label: 'Region', key: region.col('id'), name: region.col('name'), empty: 'No region'
+		}),
+		tag: dimension.manyToMany({
+			label: 'Tag',
+			through: {
+				table: orderTag,
+				on: eq(orderTag.col('orderId'), order.col('id')),
+				key: tag.col('id'),
+				name: tag.col('name')
+			},
+			note: 'An order with several tags counts once per tag.'
+		}),
+		size: dimension.computed({
+			label: 'Size',
+			expr: caseWhen([[gte(order.col('amount'), 1000), 'large']], 'small'),
+			values: { large: 'Large', small: 'Small' }
+		}),
+		week: dimension.timeBucket('created', 'week'),
+		hour: dimension.timePart('created', 'hour')
+	}
+})
+
+export const analytics = createAnalytics({
+	datasets: [orders],
+	sources: {
+		main: {
+			dialect: postgresDialect({ timestamps: 'utc' }),
+			// Run read-only, with a statement timeout, through any driver.
+			execute: ({ text, values }) => db.unsafe(text, [...values])
+		}
+	},
+	tenant: (ctx: Ctx) => ctx.organizationId,
+	authorize: (dataset, ctx) => ctx.can(`analytics:${dataset.key}`),
+	timezone: (ctx) => ctx.timezone,
+	onQuery: (event, ctx) => metrics.record(event.dataset, event.durationMs, event.outcome)
+})
+
+const result = await analytics.query(
+	{
+		dataset: 'orders',
+		measures: ['orders', 'paidShare'],
+		groupBy: ['status'],
+		filters: [{ dimension: 'tag', op: 'in', values: ['Complaint'] }],
+		period: { last: { days: 30 } },
+		compareToPrevious: true
+	},
+	ctx
+)
+result.rows[0]?.status.key // 'OPEN' | 'PAID' | 'REFUNDED'
+result.rows[0]?.paidShare // Ratio | null
+```
+
+## Callers and tools
+
+`authorize` is the one access rule. Everything that offers datasets goes through it:
+
+- `analytics.listDatasets(ctx)` resolves to the catalog entries (measures, dimensions, closed
+  values) of the datasets `ctx` may query.
+- `analytics.querySchema({ ctx })` resolves to the input schema for those datasets, for a tool
+  built per caller. It rejects with `AnalyticsError('forbidden')` when nothing is allowed.
+  `analytics.querySchema({ datasets })` is the synchronous form for a list you already have
+  (typed for those datasets only), and `querySchema()` covers every dataset. Schemas are built once per set of datasets, so
+  `querySchema({ ctx })` returns the same object as `querySchema({ datasets })` for the same
+  allowed set: cache a tool built from it by its dataset keys.
+- `analytics.query` checks `authorize` again on every call, so a schema offered too widely
+  still cannot leak a dataset.
+
+`AnalyticsResultSchema` is any dataset's result without its keys: rows of `{ key, label }`
+per grouped dimension and a number or null per measure, with totals, `previous?`, `notes` and
+`truncated`. `analytics.resultSchema(key)` is the same envelope with the dataset's fields, so a
+result that passes one passes the other. Use it for a tool's output contract.
+
+`analyticsToolGuidance` is a few markdown bullets for a model's instructions: use the tool for
+every how-many, how-much, per-period or split-by question and never count from lists; state the
+period and filters; compare with the previous period when the change is the point; say when
+grouped rows overlap; ask only when the period is genuinely ambiguous. It does not name the
+tool, so add a line that does:
+
+```ts
+const instructions = `# Numbers
+The analytics tool is analytics_query.
+${analyticsToolGuidance}`
+```
+
+`onQuery(event, ctx)` hears every `query` once it succeeds or fails:
+`{ dataset, durationMs, rows, outcome: 'success' | 'error', error? }`. `dataset` is null when
+the input named no known dataset, so free text from a model never becomes a metric label.
+What the hook throws or rejects with is swallowed; it cannot fail a query.
+
+## The model
+
+| Concept | What it is |
+| --- | --- |
+| Dataset | One fact table: tenant column, optional scope, time fields, measures, dimensions, source. |
+| Measure | `count`, `countWhere`, `countDistinct`, `sum`, `avg`, `median`, `share` (one condition over another) or `ratio` (one measure over another, after aggregation). |
+| Dimension | `enum`, `computed` (closed value sets), `relation` (to-one), `manyToMany`, `number`, `timeBucket` (day, ISO week, month), `timePart` (ISO weekday, hour). |
+| Query | `dataset`, 1-4 `measures`, 0-2 `groupBy`, `filters`, `period`, `time`, `compareToPrevious`, `sort` (by an asked measure or grouped dimension), `limit` (1-100, default 20). |
+| Result | `{ period, rows, totals, previous?, notes, truncated }`. |
+
+**Operators per dimension kind.** Closed and open dimensions take `in`, `notIn`, `isEmpty`
+and `isNotEmpty`; numeric and time dimensions take `between`, `isEmpty` and `isNotEmpty`. The
+query types and the generated schema both enforce this. `notIn` keeps rows without a value,
+unlike SQL's `NOT IN`.
+
+**Open values are keys or labels.** Filters on `relation` and `manyToMany` dimensions accept
+keys or names (case-insensitive); the engine resolves them before planning. An unknown value
+fails with `AnalyticsError('unknown_value')` listing the valid values, so a model can retry
+once.
+
+**Errors carry typed details.** `isAnalyticsError(error, code?)` narrows by code:
+`unknown_value` details are `{ dimension, unknown, valid }` and `invalid_query` details are the
+schema's issues; the other codes have none.
+
+```ts
+try {
+	return await analytics.query(input, ctx)
+} catch (error) {
+	if (isAnalyticsError(error, 'unknown_value')) return { retryWith: error.details.valid }
+	throw error
+}
+```
+
+**Periods** are whole local days in the tenant's timezone (`timezone` hook, UTC by default):
+`{ last: { days } }`, `{ from, to }` (inclusive ISO dates) or `{ preset }` (`today`,
+`yesterday`, `thisWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `thisYear`). At most two years.
+The previous period has the same length and ends the day before. Time buckets use the same
+timezone. `time` picks the time field the period applies to; a time dimension names its own.
+
+**Totals are a separate, ungrouped statement**, so a many-to-many grouping (an order with
+two tags appears in two rows) never inflates them. Filters on many-to-many dimensions compile
+to `EXISTS`, so they never multiply rows either.
+
+**Result types are honest.** `count` measures are `number`; `sum`, `avg` and `median` are
+`number | null`; `share` and `ratio` are a branded `Ratio | null` (0-1). A row has a field only
+for the dimensions it was grouped by. Relation, many-to-many, number and time keys may be
+null (no related row, no value). Enum and computed keys are null only when their expression
+can be: a nullable enum column, or a `caseWhen` without `otherwise`. Name that group with
+`empty` (default "None"), or `coalesce` the column to a value.
+
+## Types that do the work
+
+- `table<Row>(name).col(key)` only accepts keys of `Row` whose type maps to SQL
+  (`number`/`bigint`/Decimal → number, `string` → string, `boolean`, `Date` → timestamp). JSON
+  and relation fields are excluded.
+- Operands must match: `eq(numberColumn, 'x')` fails. A column keeps its value type, so
+  `eq(order.col('status'), 'PAD')` and `inList(order.col('status'), ['CLOSED'])` fail on an
+  enum column (`toText` compares with anything). `.add/.sub/.mul/.div` exist only on number
+  expressions; `div` is always floating-point and null when dividing by zero.
+- `measure.avg/sum/median` take numbers, `measure.share` takes booleans, time fields take
+  timestamps.
+- Expressions know whether they can be null. A nullable or optional field gives a nullable
+  column; `caseWhen` without `otherwise` is nullable; `coalesce` with a plain fallback is not.
+  Plain operands are never null, so `eq(column, null)` fails: use `isNull`.
+- `dimension.enum` needs a label for every enum value, and fails when the column can hold a
+  value the enum does not list.
+- `dimension.computed` fails when `values` misses a value its `caseWhen` can produce.
+- `dimension.relation` takes its key type from the key column, so a branded id column types
+  the key in filters and rows; `relation<number>` over a string column fails.
+- `groupOnly` dimensions cannot be named in `filters`, and `filterOnly` ones cannot be named
+  in `groupBy` or `sort`.
+- `measure.ratio('a', 'b')` must name measures of the same dataset; time dimensions must name
+  declared time fields.
+- `AnalyticsQuery<typeof analytics>` is the query union; `analytics.query` returns rows typed
+  by the query's `measures` and `groupBy`.
+
+What the types cannot see, `defineDataset` checks when the module loads: every column is
+reachable from the dataset's table (joins, `exists` subqueries, the many-to-many link), ratio
+measures have no cycles, and a computed dimension's `values` cover every value its expression
+can produce (repeating the type check for expressions typed only as `string`). `createAnalytics` then checks every dataset's source exists and compiles every
+measure, grouping and filter once, so a definition the dialect cannot render fails at startup.
+
+## Sources and dialects
+
+A source is `{ dialect, execute }`. `execute` receives `{ text, values }` (positional values
+for the `$n` placeholders) and returns rows as plain objects. Read-only transactions, statement timeouts and row
+caps belong in `execute`. A dataset names its source with `source`; with one source it is the
+default.
+
+Rows can come back as the driver returns them. The dialect's `decodeNumber` accepts numbers,
+numeric strings, bigints and decimal objects with a `toNumber()` method (Prisma's `Decimal`,
+decimal.js); anything else is null. Relation keys that are numbers decode the same way.
+
+For example, Prisma in a read-only transaction that Postgres stops after five seconds:
+
+```ts
+const STATEMENT_TIMEOUT_MS = 5_000
+
+const main: AnalyticsSource = {
+	dialect: postgresDialect({ timestamps: 'utc' }),
+	execute: ({ text, values }) =>
+		prisma.$transaction(
+			async (tx) => {
+				await tx.$executeRawUnsafe('SET TRANSACTION READ ONLY')
+				await tx.$executeRawUnsafe(`SET LOCAL statement_timeout = ${STATEMENT_TIMEOUT_MS}`)
+				return tx.$queryRawUnsafe<Record<string, unknown>[]>(text, ...values)
+			},
+			{ timeout: STATEMENT_TIMEOUT_MS + 1_000 }
+		)
+}
+```
+
+**`measurr/postgres`** `postgresDialect({ timestamps })`: `$n` parameters (untyped,
+so Postgres infers them from the column, which keeps enum columns working), double-quoted
+identifiers, `FILTER (WHERE ...)`, `count(DISTINCT ...)`, `percentile_cont`, correlated
+`EXISTS`, buckets with `AT TIME ZONE`, GROUP BY by position. Set `timestamps: 'utc'` for
+`timestamp without time zone` columns that hold UTC (Prisma's `DateTime`); the default
+`'timestamptz'` is for `timestamp with time zone`.
+
+## Testing your datasets
+
+`measurr/testing` runs the same checks for every dataset against a seeded database:
+
+```ts
+import { assertDatasetContract } from 'measurr/testing'
+
+await assertDatasetContract({ dataset: orders, source, tenant: seededTenantId })
+```
+
+It checks that every measure runs and returns a number or null, every grouping runs and its
+groups add up to the total (except many-to-many), `isEmpty` plus `isNotEmpty` equals the total,
+open dimensions filter by label to their group's count, closed dimensions filter by value, an
+empty tenant sees nothing (tenant isolation), and day buckets in a far-from-UTC timezone
+(default `Pacific/Auckland`) agree with single-day periods.
+
+## Extending
+
+- **A measure or dimension** is one entry in a dataset. Dimensions are groupable and
+  filterable unless `groupOnly` or `filterOnly` says otherwise. The contract kit covers it
+  without a new test.
+- **A dataset** is one `defineDataset` call added to `createAnalytics({ datasets })`.
+- **A computed value** is written with the expression builders (`caseWhen`, `exists`,
+  `coalesce`, `toText`, `minutesAgo`, comparisons, `and`/`or`/`not`), never SQL. When a
+  definition needs something they cannot say, add a builder and render it in every dialect.
+- **A dialect** implements `Dialect` (`name`, `compile`, `decodeNumber`). Most dialects only
+  provide a `SqlRenderer` (quoting, parameters, aggregates, division, time buckets and parts)
+  and call `renderStatement`. It is done when the snapshot tests and the
+  contract kit pass on it.
+
+## Stable API
+
+Kept stable for publishing: `createAnalytics` and its options, `analytics.query`,
+`explain`, `querySchema`, `resultSchema`, `listDatasets`; `AnalyticsResultSchema`,
+`analyticsToolGuidance`, `AnalyticsQueryEvent`; `defineDataset`, `measure.*`,
+`dimension.*`, `table` / `Table`, the expression builders; the `Dialect`, `SqlRenderer` and
+`AnalyticsSource` contracts; `postgresDialect`, `checkDatasetContract` /
+`assertDatasetContract`; and the types
+`AnalyticsQuery`, `AnalyticsResult`, `Ratio`, `AnalyticsError` codes and their details
+(`isAnalyticsError`). `ExprNode` and `SelectStatement` are
+exported for dialect authors and may grow new node kinds.
+
+## Install
+
+```sh
+npm install measurr zod
+```
+
+`zod` 4 is a peer dependency. The types need TypeScript 6 or newer.
+
+## Development
+
+```sh
+bun install
+bun run lint   # types and Biome
+bun test
+# With a throwaway Postgres (the integration test creates and drops its own tables):
+ANALYTICS_TEST_DATABASE_URL=postgres://... bun test
+bun run build && bun run verify:package
+```
+
+The integration test reads `ANALYTICS_TEST_DATABASE_URL`, not `DATABASE_URL`, because Bun
+loads `.env` files and that name may point at a real database. CI runs it against Postgres 17.
+
+Releases are automated with Release Please; see [docs/releasing.md](docs/releasing.md).
+
+## License
+
+MIT

package/dist/analytics.d.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import type { CompiledStatement, Dialect } from './compile.js';
+import type { AnyDataset, AnyDimension } from './dataset.js';
+import { type DatasetQuery, type QueryResult, type ResultOf } from './query.js';
+export type Row = Record<string, unknown>;
+/** A database: a dialect to compile with and a function that runs the compiled SQL. */
+export type AnalyticsSource = {
+    readonly dialect: Dialect;
+    /** Runs one read-only statement and returns its rows as plain objects. */
+    execute(statement: CompiledStatement): Promise<readonly Row[]>;
+};
+export type AnalyticsErrorCode = 'invalid_query' | 'forbidden' | 'missing_tenant' | 'invalid_timezone' | 'invalid_period' | 'unknown_value';
+/** What `details` holds for each error code. */
+export type AnalyticsErrorDetails = {
+    /** The schema's issues, for a model to fix its query. */
+    invalid_query: readonly z.core.$ZodIssue[];
+    forbidden: undefined;
+    missing_tenant: undefined;
+    invalid_timezone: undefined;
+    invalid_period: undefined;
+    /** The values that matched nothing, and the values that exist. */
+    unknown_value: {
+        dimension: string;
+        unknown: string[];
+        valid: {
+            key: string;
+            label: string;
+        }[];
+    };
+};
+export declare class AnalyticsError<C extends AnalyticsErrorCode = AnalyticsErrorCode> extends Error {
+    readonly code: C;
+    readonly name = "AnalyticsError";
+    readonly details: AnalyticsErrorDetails[C];
+    constructor(code: C, message: string, ...[details]: AnalyticsErrorDetails[C] extends undefined ? [] : [details: AnalyticsErrorDetails[C]]);
+}
+/** One `AnalyticsError` type per code, so checking `code` narrows `details`. */
+export type AnalyticsErrorOf<C extends AnalyticsErrorCode = AnalyticsErrorCode> = C extends AnalyticsErrorCode ? AnalyticsError<C> : never;
+/**
+ * Whether `error` is an `AnalyticsError` (with `code`, when given). The result narrows by
+ * code: `if (isAnalyticsError(error, 'unknown_value')) error.details.valid`.
+ */
+export declare function isAnalyticsError<C extends AnalyticsErrorCode = AnalyticsErrorCode>(error: unknown, code?: C): error is AnalyticsErrorOf<C>;
+/** What `onQuery` hears about each `analytics.query` call. */
+export type AnalyticsQueryEvent = {
+    /** The dataset asked for; null when the input named no known dataset. */
+    dataset: string | null;
+    durationMs: number;
+    /** Rows returned; 0 on error. */
+    rows: number;
+    outcome: 'success' | 'error';
+    /** What the query threw, on error. */
+    error?: unknown;
+};
+export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
+    datasets: DS;
+    /** Databases by name; a dataset's `source` picks one, or the only one is used. */
+    sources: Record<string, AnalyticsSource>;
+    /** The tenant every query is scoped to. Queries without one are refused. */
+    tenant: (ctx: Ctx) => string | number | null | undefined;
+    /**
+     * Whether `ctx` may query `dataset`. Everything is allowed when omitted. It decides what
+     * `listDatasets(ctx)` and `querySchema({ ctx })` offer, and is checked again on every query.
+     */
+    authorize?: ((dataset: DS[number], ctx: Ctx) => boolean | Promise<boolean>) | undefined;
+    /** IANA timezone periods and time buckets resolve in. UTC when omitted. */
+    timezone?: ((ctx: Ctx) => string | null | undefined | Promise<string | null | undefined>) | undefined;
+    /** The clock periods and `minutesAgo` resolve against. */
+    now?: (() => Date) | undefined;
+    /**
+     * Called once per `query`, after it succeeds or fails: for metrics and logs. What it
+     * throws or rejects with is swallowed, so it can never fail a query.
+     */
+    onQuery?: ((event: AnalyticsQueryEvent, ctx: Ctx) => unknown) | undefined;
+};
+export type DatasetCatalogEntry<Key extends string = string> = {
+    key: Key;
+    label: string;
+    description: string;
+    time: {
+        key: string;
+        label: string;
+    }[];
+    measures: {
+        key: string;
+        label: string;
+        description: string | undefined;
+    }[];
+    dimensions: {
+        key: string;
+        label: string;
+        description: string | undefined;
+        kind: AnyDimension['kind'];
+        category: AnyDimension['category'];
+        groupable: boolean;
+        filterable: boolean;
+        values: {
+            key: string;
+            label: string;
+        }[] | undefined;
+    }[];
+};
+export type Analytics<DS extends readonly AnyDataset[], Ctx> = {
+    readonly datasets: DS;
+    /** Parses, authorizes, plans, compiles, runs and shapes one query. */
+    query<const Q extends DatasetQuery<DS[number]>>(input: Q, ctx: Ctx): Promise<ResultOf<DS[number], Q>>;
+    /** The compiled statements a query would run, without running them or resolving labels. */
+    explain(input: DatasetQuery<DS[number]>, ctx: Ctx): Promise<CompiledStatement[]>;
+    /**
+     * The input schema: a discriminated union on `dataset`, for the datasets listed (all when
+     * omitted), typed for those datasets only. One schema is built per set of datasets and
+     * reused.
+     */
+    querySchema<const K extends DS[number]['key'] = DS[number]['key']>(options?: {
+        datasets?: readonly K[] | undefined;
+    }): z.ZodType<DatasetQuery<Extract<DS[number], {
+        key: K;
+    }>>>;
+    /**
+     * The input schema for the datasets `authorize` allows `ctx`, for a tool built per caller.
+     * Rejects with `forbidden` when none are allowed.
+     */
+    querySchema(options: {
+        ctx: Ctx;
+    }): Promise<z.ZodType<DatasetQuery<DS[number]>>>;
+    /** The result schema for one dataset. */
+    resultSchema(dataset: DS[number]['key']): z.ZodType<QueryResult<Row, Row>>;
+    /** The datasets `authorize` allows `ctx`, with their measures and dimensions. */
+    listDatasets(ctx: Ctx): Promise<DatasetCatalogEntry<DS[number]['key']>[]>;
+};
+export type AnalyticsQuery<A> = A extends Analytics<infer DS, never> ? DatasetQuery<DS[number]> : never;
+export type AnalyticsResult<A, Q> = A extends Analytics<infer DS, never> ? ResultOf<DS[number], Q> : never;
+export declare function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(options: AnalyticsOptions<DS, Ctx>): Analytics<DS, Ctx>;

package/dist/compile.d.ts

@@ -0,0 +1,84 @@
+import { type AggregateFn, type ExprNode, type ParamValue, type TableRef, type TimeBucketUnit, type TimePartName } from './expr.js';
+/**
+ * A planned query, still free of SQL. The planner builds it; a dialect renders it. Joins are
+ * not listed: the renderer adds exactly the joins the statement's columns need.
+ */
+export type SelectStatement = {
+    readonly from: TableRef;
+    /**
+     * Joins for standalone tables (a many-to-many link table) that apply only when one of
+     * their columns is used.
+     */
+    readonly virtualJoins: readonly JoinClause[];
+    readonly where: readonly ExprNode[];
+    readonly select: readonly SelectItem[];
+    /** Indexes into `select`. */
+    readonly groupBy: readonly number[];
+    readonly orderBy: readonly {
+        index: number;
+        direction: 'asc' | 'desc';
+    }[];
+    readonly limit: number | null;
+    /** The moment the query runs; `minutesAgo` expressions count back from it. */
+    readonly now: Date;
+};
+export type SelectItem = {
+    readonly alias: string;
+    readonly node: ExprNode;
+};
+export type JoinClause = {
+    readonly table: TableRef;
+    readonly type: 'left' | 'inner';
+    readonly on: ExprNode;
+};
+/** SQL text plus its positional parameters. */
+export type CompiledStatement = {
+    readonly text: string;
+    readonly values: readonly unknown[];
+};
+/**
+ * Everything a database needs: it renders statements and decodes what comes back. A dialect
+ * has no driver dependency; the app's `execute` runs the SQL. Postgres ships in this package;
+ * another database plugs in by implementing this, usually through a `SqlRenderer`.
+ */
+export type Dialect = {
+    readonly name: string;
+    compile(statement: SelectStatement): CompiledStatement;
+    /**
+     * Numbers may arrive as strings or bigints (numerics, 64-bit integers), or as decimal
+     * objects (Prisma's `Decimal`).
+     */
+    decodeNumber(value: unknown): number | null;
+};
+/** The places where SQL differs between databases. `renderStatement` handles the rest. */
+export type SqlRenderer = {
+    readonly name: string;
+    quote(identifier: string): string;
+    /** Registers a parameter and returns its placeholder. `index` is 1-based. */
+    param(value: ParamValue, index: number): {
+        placeholder: string;
+        value: unknown;
+    };
+    aggregate(fn: AggregateFn, arg: string | null, where: string | null): string;
+    /** Floating-point division that is null when dividing by zero. */
+    divide(left: string, right: string): string;
+    toText(expr: string): string;
+    /** A `YYYY-MM-DD` string of the bucket's first day in `timezone`. */
+    timeBucket(unit: TimeBucketUnit, expr: string, timezone: string): string;
+    /** An integer: ISO weekday 1-7 or hour 0-23 in `timezone`. */
+    timePart(part: TimePartName, expr: string, timezone: string): string;
+};
+export declare class CompileError extends Error {
+    readonly name = "CompileError";
+}
+/**
+ * Decodes numbers the way drivers return them: numbers, numeric strings, bigints and decimal
+ * objects with a `toNumber()` method (Prisma's `Decimal`, decimal.js). Anything else is null.
+ */
+export declare function decodeNumber(value: unknown): number | null;
+export declare function renderStatement(statement: SelectStatement, renderer: SqlRenderer): CompiledStatement;
+/**
+ * The joins `nodes` need, parents before children and `ON` dependencies before the join that
+ * uses them. Columns of other roots (such as a subquery's own table) are left alone.
+ */
+export declare function collectJoins(nodes: readonly ExprNode[], root: TableRef, virtualJoins: readonly JoinClause[]): JoinClause[];