@softr/sdk 0.0.25 → 0.0.26

package/dist/datasource/chart.d.ts

@@ -0,0 +1,196 @@
+import { Action, FieldTypeOf, ReadShape, SoftrDatasources } from "../action.js";
+import { ConstructableOrderBy } from "./filter.js";
+import { DateFieldType, NumberFieldType, SortSet } from "./fields.js";
+import { WhereCallback } from "./record.js";
+
+//#region src/datasource/chart.d.ts
+declare const dimensionValue: unique symbol;
+declare const measureValue: unique symbol;
+/** A chart column that groups rows. The brand carries the value type the column reads back as. */
+type Dimension<TValue$1> = {
+  readonly [dimensionValue]: TValue$1;
+};
+/** A chart column that aggregates rows. The brand carries the value type the column reads back as. */
+type Measure<TValue$1> = {
+  readonly [measureValue]: TValue$1;
+};
+type ColumnValue<T> = T extends Dimension<infer TValue> ? TValue : T extends Measure<infer TValue> ? TValue : never;
+type DateBuckets = {
+  /** Groups by calendar day. The value reads as `"2025-06-14"`. */
+  readonly byDay: Dimension<string | null>;
+  /**
+   * Groups by calendar week. The value is the ISO date of the week's Monday. Monday-based,
+   * while `byDayOfWeek` counts from Sunday: the server disagrees with itself, so the two
+   * cannot be lined up by arithmetic alone.
+   */
+  readonly byWeek: Dimension<string | null>;
+  /** Groups by calendar month. The value reads as `"2025-06"`. */
+  readonly byMonth: Dimension<string | null>;
+  /** Groups by calendar quarter. The value is a display string like `"Q2 2025"`, not a parseable date. */
+  readonly byQuarter: Dimension<string | null>;
+  /** Groups by calendar year. The value is the year as a number. */
+  readonly byYear: Dimension<number | null>;
+  /**
+   * Groups by day of week, 1 through 7 with 1 as Sunday. Sunday-based, while `byWeek` is
+   * Monday-based: the server disagrees with itself, so the two cannot be lined up by
+   * arithmetic alone.
+   */
+  readonly byDayOfWeek: Dimension<number | null>;
+  /** Groups by month of year, 1 through 12. */
+  readonly byMonthOfYear: Dimension<number | null>;
+  /** Groups by quarter of year, 1 through 4. */
+  readonly byQuarterOfYear: Dimension<number | null>;
+};
+type DatetimeBuckets = DateBuckets & {
+  /** Groups by hour of day, 0 through 23. */
+  readonly byHourOfDay: Dimension<number | null>;
+};
+type DateDimension = Dimension<string | null> & DateBuckets;
+type DatetimeDimension = Dimension<string | null> & DatetimeBuckets;
+type NumericMeasures = {
+  /** Adds the group's values. `null` when the group has none. */
+  readonly sum: Measure<number | null>;
+  /** Averages the group's values, rounded to two decimals. `null` when the group has none. */
+  readonly avg: Measure<number | null>;
+  /** The group's smallest value. `null` when the group has none. */
+  readonly min: Measure<number | null>;
+  /** The group's largest value. `null` when the group has none. */
+  readonly max: Measure<number | null>;
+  /** Counts the group's distinct values. */
+  readonly distinct: Measure<number>;
+};
+type DateMeasures = {
+  /** The group's earliest date, as `"2025-06-14"`. `null` when the group has none. */
+  readonly min: Measure<string | null>;
+  /** The group's latest date, as `"2025-06-14"`. `null` when the group has none. */
+  readonly max: Measure<string | null>;
+  /** Counts the group's distinct values. */
+  readonly distinct: Measure<number>;
+};
+type AnyDimension = Dimension<unknown> & DatetimeBuckets;
+type AnyMeasures = {
+  readonly sum: Measure<number | null>;
+  readonly avg: Measure<number | null>;
+  readonly min: Measure<unknown>;
+  readonly max: Measure<unknown>;
+  readonly distinct: Measure<number>;
+};
+/** A field a chart cannot use for this: the missing leaves are the compile error saying so. */
+type Unusable = {
+  readonly [dimensionValue]?: never;
+};
+/**
+ * The handles a `groupBy` callback is handed: one per alias. The bare handle groups by the
+ * field's value; a date field also carries bucket leaves. A multi-value field has no handle
+ * body, because exploding it would count each record once per value and inflate every metric.
+ */
+type DimensionSet<TShape extends ReadShape> = keyof SoftrDatasources extends never ? Record<string, AnyDimension> : { [Alias in keyof TShape["fields"]]: DimensionFor<FieldTypeOf<TShape["datasource"], TShape["fields"][Alias]>> };
+type DimensionFor<TFieldType> = [TFieldType] extends [never] ? AnyDimension : TFieldType extends `${string}[]` | "ATTACHMENT" | "DATE_RANGE" ? Unusable : TFieldType extends "DATE" ? DateDimension : TFieldType extends DateFieldType ? DatetimeDimension : TFieldType extends NumberFieldType ? Dimension<number | null> : TFieldType extends "CHECKBOX" ? Dimension<boolean | null> : Dimension<string | null>;
+/**
+ * The handles a `metrics` callback is handed: aggregation leaves per alias, gated by the
+ * field's declared type, plus `$count`. A field whose aggregate would come back as a
+ * coerced non-number has no leaves at all.
+ */
+type MeasureSet<TShape extends ReadShape> = (keyof SoftrDatasources extends never ? Record<string, AnyMeasures> : { [Alias in keyof TShape["fields"]]: MeasureFor<FieldTypeOf<TShape["datasource"], TShape["fields"][Alias]>> }) & {
+  /** Counts the rows in each group. Takes no field: every row counts once. */
+  readonly $count: Measure<number>;
+};
+type MeasureFor<TFieldType> = [TFieldType] extends [never] ? AnyMeasures : TFieldType extends `${string}[]` ? Unusable : TFieldType extends NumberFieldType ? NumericMeasures : TFieldType extends DateFieldType ? DateMeasures : Unusable;
+type IsUnion<T, TAll = T> = [T] extends [never] ? false : T extends unknown ? [TAll] extends [T] ? false : true : never;
+type MoreThanTwo<TKeys, TAll = TKeys> = TKeys extends unknown ? IsUnion<Exclude<TAll, TKeys>> : never;
+type GroupByBounds<TGroups> = [keyof TGroups] extends [never] ? {
+  __error: "a chart needs at least one column to group by";
+} : true extends MoreThanTwo<keyof TGroups> ? {
+  __error: "a chart may group by at most two columns";
+} : unknown;
+type MetricBounds<TMetrics, TGroups> = [Extract<keyof TMetrics, keyof TGroups>] extends [never] ? unknown : {
+  __error: "a metric key must not collide with a group key";
+};
+/** One row, keyed by the caller's own `groupBy` and `metrics` keys. */
+type ChartRow<TGroups, TMetrics> = { [K in keyof TGroups | keyof TMetrics]: ColumnValue<(TGroups & TMetrics)[K]> };
+interface ChartResult<TRow> {
+  data: Array<TRow>;
+  executionTimestamp: Date;
+}
+/** A chart before `groupBy`. It cannot be awaited: an un-grouped chart is not a request. */
+type ChartSeed<TShape extends ReadShape> = {
+  /**
+   * Names the group columns: one or two entries, each a handle from the callback, keyed by
+   * the name the row will carry. A bare handle groups by the field's value; a bucket leaf
+   * such as `q.closedAt.byMonth` groups a date field by the bucket.
+   *
+   * @example
+   * ds.chart(sales).groupBy((q) => ({ month: q.closedAt.byMonth, region: q.region }))
+   */
+  groupBy<TGroups extends Record<string, Dimension<unknown>>>(build: (q: DimensionSet<TShape>) => TGroups & GroupByBounds<TGroups>): ChartBuilder<TShape, TGroups, {}>;
+  /**
+   * Narrows which records the chart aggregates. Same filters as `ds.list`.
+   */
+  where(build: WhereCallback<TShape>): ChartSeed<TShape>;
+};
+type ChartBuilder<TShape extends ReadShape, TGroups, TMetrics> = {
+  /**
+   * Names the aggregated columns, keyed by the name the row will carry. Omit the call for a
+   * distinct-values query: the rows then hold the group columns alone.
+   *
+   * @example
+   * ds.chart(sales)
+   *   .groupBy((q) => ({ region: q.region }))
+   *   .metrics((q) => ({ revenue: q.amount.sum, orders: q.$count }))
+   */
+  metrics<TNext extends Record<string, Measure<unknown>>>(build: (q: MeasureSet<TShape>) => TNext & MetricBounds<TNext, TGroups>): ChartBuilder<TShape, TGroups, TNext>;
+  /**
+   * Narrows which records the chart aggregates. Same filters as `ds.list`.
+   */
+  where(build: WhereCallback<TShape>): ChartBuilder<TShape, TGroups, TMetrics>;
+  /**
+   * Sorts the rows by the chart's own keys. Call it last: it sees the keys declared so far,
+   * so placed before `metrics` a metric key is not yet a column. Without a sort the rows come
+   * back by the first bucket ascending, else by the first metric descending.
+   *
+   * @example
+   * ds.chart(sales)
+   *   .groupBy((q) => ({ month: q.closedAt.byMonth }))
+   *   .metrics((q) => ({ revenue: q.amount.sum }))
+   *   .orderBy((q) => [q.month.asc, q.revenue.desc])
+   */
+  orderBy(build: (q: SortSet<ChartRow<TGroups, TMetrics>>) => ConstructableOrderBy | Array<ConstructableOrderBy>): ChartBuilder<TShape, TGroups, TMetrics>;
+} & Promise<ChartResult<ChartRow<TGroups, TMetrics>>>;
+interface MetricResult<TValue$1> {
+  value: TValue$1;
+  executionTimestamp: Date;
+}
+type MetricBuilder<TShape extends ReadShape, TValue$1> = {
+  /**
+   * Narrows which records the metric aggregates. Same filters as `ds.list`.
+   */
+  where(build: WhereCallback<TShape>): MetricBuilder<TShape, TValue$1>;
+} & Promise<MetricResult<TValue$1>>;
+/**
+ * Aggregates records into chart rows: one row per group, keyed by the caller's own names.
+ *
+ * `groupBy` is required and takes one or two columns. `metrics` is optional; without it the
+ * rows hold the distinct group values. `orderBy` comes last, over the chart's own keys.
+ *
+ * @example
+ * const { data } = await ds
+ *   .chart(sales)
+ *   .groupBy((q) => ({ month: q.closedAt.byMonth }))
+ *   .metrics((q) => ({ revenue: q.amount.sum, orders: q.$count }))
+ *   .where((q) => q.status.is("paid"))
+ *   .orderBy((q) => q.month.asc)
+ * // data: Array<{ month: string | null; revenue: number | null; orders: number }>
+ */
+declare function chart<TShape extends ReadShape>(query: Action<TShape>): ChartSeed<TShape>;
+/**
+ * Aggregates records into one value, with no grouping.
+ *
+ * @example
+ * const { value } = await ds
+ *   .metric(sales, (q) => q.amount.sum)
+ *   .where((q) => q.status.is("paid"))
+ * // value: number | null
+ */
+declare function metric<TShape extends ReadShape, TMeasure extends Measure<unknown>>(query: Action<TShape>, pick: (q: MeasureSet<TShape>) => TMeasure): MetricBuilder<TShape, ColumnValue<TMeasure>>;
+//#endregion
+export { chart, metric };

package/dist/datasource/chart.js

@@ -0,0 +1,289 @@
+import { assert, panic } from "../assertions.js";
+import { readUserTimezone } from "../cookies.js";
+import { readSessionToken } from "../auth/session.js";
+import { INTERNAL_KIND, buildFilterCriteria, buildOrderBy, dealiasFilterCriteria } from "./filter.js";
+import { andAll, makeFieldSet, makeSortSet } from "./fields.js";
+import { dsUrl, resolveTarget } from "./record.js";
+
+//#region src/datasource/chart.ts
+const COUNT_CNT = "COUNT_CNT";
+function makeDimensionSet(select) {
+	const set = {};
+	for (const [alias, fieldId] of Object.entries(select)) set[alias] = Object.assign(dimension(fieldId), {
+		byDay: dimension(fieldId, {
+			timeInterval: "DAY",
+			displayFormat: "YYYY-MM-DD"
+		}),
+		byWeek: dimension(fieldId, { timeInterval: "WEEK" }),
+		byMonth: dimension(fieldId, {
+			timeInterval: "MONTH",
+			displayFormat: "YYYY-MM"
+		}),
+		byQuarter: dimension(fieldId, { timeInterval: "QUARTER" }),
+		byYear: dimension(fieldId, { timeInterval: "YEAR" }),
+		byHourOfDay: dimension(fieldId, { timeInterval: "HOUR_OF_DAY" }),
+		byDayOfWeek: dimension(fieldId, { timeInterval: "DAY_OF_WEEK" }),
+		byMonthOfYear: dimension(fieldId, { timeInterval: "MONTH_OF_YEAR" }),
+		byQuarterOfYear: dimension(fieldId, { timeInterval: "QUARTER_OF_YEAR" })
+	});
+	return set;
+}
+function dimension(fieldId, options) {
+	return options ? {
+		fieldId,
+		options,
+		[INTERNAL_KIND]: "DIMENSION"
+	} : {
+		fieldId,
+		[INTERNAL_KIND]: "DIMENSION"
+	};
+}
+function makeMeasureSet(select) {
+	const set = {};
+	for (const [alias, fieldId] of Object.entries(select)) set[alias] = {
+		sum: measure("SUM", fieldId),
+		avg: measure("AVG", fieldId),
+		min: measure("MIN", fieldId),
+		max: measure("MAX", fieldId),
+		distinct: measure("DISTINCT", fieldId)
+	};
+	set["$count"] = {
+		aggregation: "COUNT",
+		fieldId: null,
+		[INTERNAL_KIND]: "MEASURE"
+	};
+	return set;
+}
+function measure(aggregation, fieldId) {
+	return {
+		aggregation,
+		fieldId,
+		[INTERNAL_KIND]: "MEASURE"
+	};
+}
+function isHandle(value, kind) {
+	return typeof value === "object" && value !== null && value[INTERNAL_KIND] === kind;
+}
+/**
+* Aggregates records into chart rows: one row per group, keyed by the caller's own names.
+*
+* `groupBy` is required and takes one or two columns. `metrics` is optional; without it the
+* rows hold the distinct group values. `orderBy` comes last, over the chart's own keys.
+*
+* @example
+* const { data } = await ds
+*   .chart(sales)
+*   .groupBy((q) => ({ month: q.closedAt.byMonth }))
+*   .metrics((q) => ({ revenue: q.amount.sum, orders: q.$count }))
+*   .where((q) => q.status.is("paid"))
+*   .orderBy((q) => q.month.asc)
+* // data: Array<{ month: string | null; revenue: number | null; orders: number }>
+*/
+function chart(query) {
+	const { select } = resolveTarget(query, "read");
+	const aliases = Object.keys(select);
+	const state = {
+		filters: [],
+		orderBys: []
+	};
+	let result;
+	const run = () => result ??= executeChart(query, state);
+	const builder = {
+		[Symbol.toStringTag]: "ChartQuery",
+		groupBy(build) {
+			assert(!state.groups, "groupBy may only be called once");
+			const entries = Object.entries(build(makeDimensionSet(select)));
+			for (const [, handle] of entries) assert(isHandle(handle, "DIMENSION"), "a chart column must come from the callback a chart hands you");
+			assert(entries.length <= 2, "a chart may group by at most two columns");
+			const groups = entries;
+			assert(groups.length < 2 || groups[0][1].fieldId !== groups[1][1].fieldId, "a chart may group by a field only once");
+			state.groups = groups;
+			return builder;
+		},
+		metrics(build) {
+			assert(!state.metrics, "metrics may only be called once");
+			const entries = Object.entries(build(makeMeasureSet(select)));
+			for (const [, handle] of entries) assert(isHandle(handle, "MEASURE"), "a chart column must come from the callback a chart hands you");
+			const metrics = entries;
+			const seen = /* @__PURE__ */ new Set();
+			for (const [, handle] of metrics) {
+				const pair = `${handle.aggregation} ${handle.fieldId ?? ""}`;
+				assert(!seen.has(pair), "two metrics ask for the same value");
+				seen.add(pair);
+			}
+			state.metrics = metrics;
+			return builder;
+		},
+		where(build) {
+			state.filters.push(build(makeFieldSet(aliases)));
+			return builder;
+		},
+		orderBy(build) {
+			const sorting = build(makeSortSet([...state.groups ?? [], ...state.metrics ?? []].map(([key]) => key)));
+			state.orderBys.push(...buildOrderBy(Array.isArray(sorting) ? sorting : [sorting]));
+			return builder;
+		},
+		then(onfulfilled, onrejected) {
+			return run().then(onfulfilled, onrejected);
+		},
+		catch(onrejected) {
+			return run().catch(onrejected);
+		},
+		finally(onfinally) {
+			return run().finally(onfinally);
+		}
+	};
+	return builder;
+}
+function buildChartRequest(state, select) {
+	const groups = state.groups;
+	assert(groups && groups.length > 0, "a chart needs at least one column to group by");
+	const metrics = state.metrics ?? [];
+	const grouped = new Set(groups.map(([, handle]) => handle.fieldId));
+	for (const [, handle] of metrics) assert(handle.fieldId === null || !grouped.has(handle.fieldId), "a field cannot be grouped and aggregated in one chart");
+	const suffixed = metrics.length > 1;
+	const columns = [...groups.map(([key, handle]) => ({
+		key,
+		responseKey: handle.fieldId
+	})), ...metrics.map(([key, handle]) => ({
+		key,
+		responseKey: handle.aggregation === "COUNT" && !handle.fieldId ? COUNT_CNT : `${handle.fieldId}${suffixed ? `_${handle.aggregation.toLowerCase()}` : ""}`
+	}))];
+	let orderBys = state.orderBys;
+	if (orderBys.length === 0) {
+		const bucketed = groups.find(([, handle]) => handle.options !== void 0);
+		const [key, sortType] = bucketed ? [bucketed[0], "ASC"] : metrics.length > 0 ? [metrics[0][0], "DESC"] : [groups[0][0], "ASC"];
+		orderBys = [{
+			sortingField: key,
+			sortType
+		}];
+	}
+	const responseKeyOf = new Map(columns.map((column) => [column.key, column.responseKey]));
+	const sortingOptions = orderBys.map((orderBy) => ({
+		sortingField: responseKeyOf.get(orderBy.sortingField) ?? panic(() => `"${orderBy.sortingField}" is not a column of this chart`),
+		sortType: orderBy.sortType
+	}));
+	return {
+		body: {
+			filterCriteria: toFilterCriteria(state.filters, select),
+			sortingOptions,
+			groupBy: groups.map(([, handle]) => handle.options ? {
+				field: handle.fieldId,
+				options: handle.options
+			} : { field: handle.fieldId }),
+			metrics: metrics.map(([, handle]) => ({
+				field: handle.fieldId ?? "",
+				aggregation: handle.aggregation
+			}))
+		},
+		columns
+	};
+}
+function mapChartRows(columns, data) {
+	return data.map((item) => {
+		const row = {};
+		for (const { key, responseKey } of columns) {
+			assert(responseKey in item, () => `the response has no column for "${key}"`);
+			row[key] = item[responseKey];
+		}
+		return row;
+	});
+}
+async function executeChart(query, state) {
+	const { datasourceId, select } = resolveTarget(query, "read");
+	const { body, columns } = buildChartRequest(state, select);
+	const res = await fetch(`${dsUrl(datasourceId)}/chart/data`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"X-User-Timezone": readUserTimezone() ?? "UTC",
+			Authorization: `Bearer ${readSessionToken()}`
+		},
+		body: JSON.stringify(body)
+	});
+	if (!res.ok) throw new Error(`Softr datasource chart failed for "${datasourceId}": ${res.status}`);
+	const payload = await res.json();
+	return {
+		data: mapChartRows(columns, payload.data),
+		executionTimestamp: /* @__PURE__ */ new Date(payload.executionTimestamp * 1e3)
+	};
+}
+/**
+* Aggregates records into one value, with no grouping.
+*
+* @example
+* const { value } = await ds
+*   .metric(sales, (q) => q.amount.sum)
+*   .where((q) => q.status.is("paid"))
+* // value: number | null
+*/
+function metric(query, pick) {
+	const { select } = resolveTarget(query, "read");
+	const aliases = Object.keys(select);
+	const picked = pick(makeMeasureSet(select));
+	assert(isHandle(picked, "MEASURE"), "a metric must come from the callback a metric hands you");
+	const handle = picked;
+	const filters = [];
+	let result;
+	const run = () => result ??= executeMetric(query, handle, filters);
+	const builder = {
+		[Symbol.toStringTag]: "MetricQuery",
+		where(build) {
+			filters.push(build(makeFieldSet(aliases)));
+			return builder;
+		},
+		then(onfulfilled, onrejected) {
+			return run().then(onfulfilled, onrejected);
+		},
+		catch(onrejected) {
+			return run().catch(onrejected);
+		},
+		finally(onfinally) {
+			return run().finally(onfinally);
+		}
+	};
+	return builder;
+}
+function buildMetricRequest(handle, filters, select) {
+	return {
+		body: {
+			groupBy: [],
+			metrics: [{
+				field: handle.fieldId ?? void 0,
+				aggregation: handle.aggregation
+			}],
+			filterCriteria: toFilterCriteria(filters, select)
+		},
+		responseKey: handle.aggregation === "COUNT" && !handle.fieldId ? COUNT_CNT : handle.fieldId
+	};
+}
+function readMetricValue(responseKey, data) {
+	const row = data.find((item) => responseKey in item);
+	assert(row, "the response has no value for the metric");
+	return row[responseKey];
+}
+async function executeMetric(query, handle, filters) {
+	const { datasourceId, select } = resolveTarget(query, "read");
+	const { body, responseKey } = buildMetricRequest(handle, filters, select);
+	const res = await fetch(`${dsUrl(datasourceId)}/chart/data`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"X-User-Timezone": readUserTimezone() ?? "UTC",
+			Authorization: `Bearer ${readSessionToken()}`
+		},
+		body: JSON.stringify(body)
+	});
+	if (!res.ok) throw new Error(`Softr datasource metric failed for "${datasourceId}": ${res.status}`);
+	const payload = await res.json();
+	return {
+		value: readMetricValue(responseKey, payload.data),
+		executionTimestamp: /* @__PURE__ */ new Date(payload.executionTimestamp * 1e3)
+	};
+}
+function toFilterCriteria(filters, select) {
+	return filters.length ? dealiasFilterCriteria(buildFilterCriteria(andAll(filters)), select) : {};
+}
+
+//#endregion
+export { chart, metric };

package/dist/datasource/datasource.d.ts

@@ -0,0 +1,16 @@
+import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
+import { chart, metric } from "./chart.js";
+import "@tanstack/react-start/server-only";
+
+//#region src/datasource/datasource.d.ts
+declare const ds: {
+  list: typeof listRecords;
+  get: typeof getRecord;
+  create: typeof createRecord;
+  update: typeof updateRecord;
+  delete: typeof deleteRecord;
+  metric: typeof metric;
+  chart: typeof chart;
+};
+//#endregion
+export { ds };

package/dist/datasource/datasource.js

@@ -0,0 +1,17 @@
+import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
+import { chart, metric } from "./chart.js";
+import "@tanstack/react-start/server-only";
+
+//#region src/datasource/datasource.ts
+const ds = {
+	list: listRecords,
+	get: getRecord,
+	create: createRecord,
+	update: updateRecord,
+	delete: deleteRecord,
+	metric,
+	chart
+};
+
+//#endregion
+export { ds };

package/dist/datasource/fields.d.ts

@@ -0,0 +1,122 @@
+import { FieldTypeOf, ReadOf, ReadShape, SoftrDatasources } from "../action.js";
+import { AnyConstructable, ConstructableFilter, ConstructableFilterGroup, ConstructableOrderBy } from "./filter.js";
+
+//#region src/datasource/fields.d.ts
+type EmptyChain = {
+  isEmpty(): ConstructableFilter;
+  isNotEmpty(): ConstructableFilter;
+};
+type BooleanChain = EmptyChain & {
+  is(value: boolean): ConstructableFilter;
+  isNot(value: boolean): ConstructableFilter;
+};
+type NumberChain = EmptyChain & {
+  is(value: number): ConstructableFilter;
+  isNot(value: number): ConstructableFilter;
+  gt(value: number): ConstructableFilter;
+  gte(value: number): ConstructableFilter;
+  lt(value: number): ConstructableFilter;
+  lte(value: number): ConstructableFilter;
+  between(start: number, end: number): ConstructableFilter;
+};
+type ArrayChain<TMember$1 extends string> = EmptyChain & {
+  is(values: Array<TMember$1>): ConstructableFilter;
+  isOneOf(values: Array<TMember$1>): ConstructableFilter;
+  isNoneOf(values: Array<TMember$1>): ConstructableFilter;
+  hasAllOf(values: Array<TMember$1>): ConstructableFilter;
+};
+type ChoiceChain<TId$1 extends string> = EmptyChain & {
+  is(value: TId$1): ConstructableFilter;
+  isNot(value: TId$1): ConstructableFilter;
+  isOneOf(values: Array<TId$1>): ConstructableFilter;
+  isNoneOf(values: Array<TId$1>): ConstructableFilter;
+};
+/** What DSv2 filters generically: matched whole or scanned, never against a set. */
+type GenericChain = EmptyChain & {
+  is(value: string): ConstructableFilter;
+  isNot(value: string): ConstructableFilter;
+  contains(value: string): ConstructableFilter;
+};
+type TextChain<TValue extends string> = EmptyChain & {
+  is(value: TValue): ConstructableFilter;
+  isNot(value: TValue): ConstructableFilter;
+  contains(value: string): ConstructableFilter;
+  startsWith(value: string): ConstructableFilter;
+  endsWith(value: string): ConstructableFilter;
+  isOneOf(values: Array<string>): ConstructableFilter;
+  isNoneOf(values: Array<string>): ConstructableFilter;
+};
+type DateChain = EmptyChain & {
+  is(value: string): ConstructableFilter;
+  isNot(value: string): ConstructableFilter;
+  gt(value: string): ConstructableFilter;
+  gte(value: string): ConstructableFilter;
+  lt(value: string): ConstructableFilter;
+  lte(value: string): ConstructableFilter;
+  between(start: string, end: string): ConstructableFilter;
+  isNotBetween(start: string, end: string): ConstructableFilter;
+};
+/** Every operator, for a field whose type nothing has generated yet. */
+type AnyChain = EmptyChain & {
+  is(value: unknown): ConstructableFilter;
+  isNot(value: unknown): ConstructableFilter;
+  contains(value: string): ConstructableFilter;
+  startsWith(value: string): ConstructableFilter;
+  endsWith(value: string): ConstructableFilter;
+  isOneOf(values: Array<string>): ConstructableFilter;
+  isNoneOf(values: Array<string>): ConstructableFilter;
+  hasAllOf(values: Array<string>): ConstructableFilter;
+  gt(value: number | string): ConstructableFilter;
+  gte(value: number | string): ConstructableFilter;
+  lt(value: number | string): ConstructableFilter;
+  lte(value: number | string): ConstructableFilter;
+  between(start: number | string, end: number | string): ConstructableFilter;
+  isNotBetween(start: number | string, end: number | string): ConstructableFilter;
+};
+type IdOf<TValue> = TValue extends {
+  id: infer TId extends string;
+} ? TId : string;
+/**
+ * What a choice-shaped field compares against: its own ids where codegen read the choice
+ * list, and any string where it did not. A linked record is the open case, and it is the
+ * only thing distinguishing one from a select at the type level.
+ */
+type ChoiceIds<TValue> = string extends IdOf<TValue> ? string : IdOf<TValue>;
+type TextFieldType = 'SINGLE_LINE_TEXT' | 'LONG_TEXT' | 'URL' | 'EMAIL' | 'PHONE' | 'ADDRESS' | 'RECORD_ID' | 'LOCATION' | 'TIME' | 'BUTTON';
+type NumberFieldType = 'NUMBER' | 'PERCENT' | 'CURRENCY' | 'PROGRESS' | 'RATING' | 'DURATION' | 'COUNT' | 'AUTONUMBER';
+type DateFieldType = 'DATE' | 'DATETIME' | 'CREATED_AT' | 'UPDATED_AT';
+type ChoiceFieldType = 'SELECT' | 'LINKED_RECORD' | 'CREATED_BY' | 'UPDATED_BY';
+/** The types with no single value to compare: only whether the field holds one. */
+type EmptyFieldType = 'ATTACHMENT' | 'DATE_RANGE';
+type ElementOf<TValue> = TValue extends Array<infer TMember> ? TMember : TValue;
+/**
+ * The operators one alias offers, chosen from the type codegen declared for the field rather
+ * than from what it reads as: a `DATETIME` and a text field both read as `string`, and only
+ * the declared type tells them apart.
+ *
+ * `TValue` is still needed for the literal choice ids, which live on the read type and
+ * nowhere else. A field with no declared type lands on the permissive chain rather than on
+ * none.
+ */
+type ChainFor<TFieldType, TValue> = [TFieldType] extends [never] ? AnyChain : TFieldType extends `${infer TBase}[]` ? TBase extends EmptyFieldType ? EmptyChain : ArrayChain<ChoiceIds<ElementOf<TValue>>> : TFieldType extends TextFieldType ? TextChain<TValue & string> : TFieldType extends NumberFieldType ? NumberChain : TFieldType extends 'USER' ? GenericChain : TFieldType extends 'CHECKBOX' ? BooleanChain : TFieldType extends DateFieldType ? DateChain : TFieldType extends ChoiceFieldType ? ChoiceChain<ChoiceIds<TValue>> : TFieldType extends EmptyFieldType ? EmptyChain : AnyChain;
+type Combinators = {
+  $and(...members: Array<AnyConstructable>): ConstructableFilterGroup;
+  $or(...members: Array<AnyConstructable>): ConstructableFilterGroup;
+};
+/**
+ * What a `where` callback is handed: every alias the action declares, already a chain of the
+ * operators that alias accepts, plus `$and` and `$or` to nest them.
+ *
+ * Keyed off the action's own `fields` map, so an alias resolves to a field id and from there
+ * to the declared type. With nothing generated there is no field id to resolve, and an alias
+ * the action never declared has to resolve too, so that case is open by name and permissive
+ * by operator.
+ */
+type FieldSet<TShape extends ReadShape> = keyof SoftrDatasources extends never ? Record<string, AnyChain> & Combinators : { [Alias in keyof TShape['fields']]: ChainFor<FieldTypeOf<TShape['datasource'], TShape['fields'][Alias]>, NonNullable<ReadOf<TShape['datasource']>[TShape['fields'][Alias] & keyof ReadOf<TShape['datasource']>]>> } & Combinators;
+/** What an `orderBy` callback is handed: two handles per alias and nothing else. */
+type SortSet<TRecord> = { [K in keyof TRecord]: {
+  readonly asc: ConstructableOrderBy;
+  readonly desc: ConstructableOrderBy;
+} };
+//#endregion
+export { DateFieldType, FieldSet, NumberFieldType, SortSet };