@10x-media/form-builder 0.1.0-beta.0 → 0.1.0-beta.1

package/dist/aggregation/aggregateResponses.js

@@ -0,0 +1,86 @@
+import { aggregateRowsForFields } from "./aggregateRows.js";
+import { FORMS_SLUG } from "../collections/forms.js";
+import { FORM_SUBMISSIONS_SLUG } from "../collections/formSubmissions.js";
+//#region src/aggregation/aggregateResponses.ts
+const optionsOf = (field) => {
+	if (!Array.isArray(field.options)) return;
+	const options = field.options.filter((option) => typeof option?.value === "string").map((option) => ({
+		value: String(option.value),
+		label: option.label ?? String(option.value)
+	}));
+	return options.length > 0 ? options : void 0;
+};
+/** True when a field declares non-empty options (a choice field safe to aggregate publicly). */
+const fieldHasOptions = (field) => optionsOf(field) !== void 0;
+const metaFor = (field) => ({
+	field: field.name,
+	label: field.label ?? field.name,
+	fieldType: field.blockType,
+	options: optionsOf(field)
+});
+/**
+* Aggregate submission responses for a form. Loads the form for current labels + option order, then pages
+* `payload.find` over its submissions (JSON `values` cannot be GROUP BY'd portably across Mongo + Postgres,
+* so we scan + reduce in JS, cross-DB-identically). Bounded by `maxSubmissions`; beyond it the result is
+* `truncated`. Returns one `FieldAggregation` per requested field (or per enumerable field by default).
+*/
+const aggregateFormResponses = async (args) => {
+	const { payload, formId, fields, status = "complete", req, maxSubmissions = 1e4, pageSize = 500 } = args;
+	const form = await payload.findByID({
+		collection: FORMS_SLUG,
+		id: formId,
+		depth: 0,
+		overrideAccess: true,
+		req
+	}).catch(() => null);
+	if (!form || !Array.isArray(form.fields)) return [];
+	const instances = form.fields;
+	const selected = fields ? instances.filter((field) => fields.includes(field.name)) : instances.filter((field) => optionsOf(field) !== void 0);
+	if (selected.length === 0) return [];
+	const metas = selected.map(metaFor);
+	const where = { and: [{ form: { equals: formId } }, ...status === "all" ? [] : [{ status: { equals: status } }]] };
+	const rows = [];
+	let page = 1;
+	let truncated = false;
+	for (;;) {
+		const result = await payload.find({
+			collection: FORM_SUBMISSIONS_SLUG,
+			where,
+			limit: pageSize,
+			page,
+			depth: 0,
+			overrideAccess: true,
+			req,
+			select: {
+				values: true,
+				descriptors: true
+			}
+		});
+		for (const doc of result.docs) {
+			if (rows.length >= maxSubmissions) {
+				truncated = true;
+				break;
+			}
+			rows.push({
+				values: doc.values,
+				descriptors: doc.descriptors
+			});
+		}
+		if (truncated || !result.hasNextPage) break;
+		page += 1;
+	}
+	return aggregateRowsForFields(rows, metas, truncated);
+};
+/** Single-field convenience over `aggregateFormResponses`. Returns the field's aggregation, or null if absent. */
+const aggregateFieldResponses = async (args) => {
+	const { field, ...rest } = args;
+	const [result] = await aggregateFormResponses({
+		...rest,
+		fields: [field]
+	});
+	return result ?? null;
+};
+//#endregion
+export { aggregateFieldResponses, aggregateFormResponses, fieldHasOptions };
+
+//# sourceMappingURL=aggregateResponses.js.map

package/dist/aggregation/aggregateResponses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregateResponses.js","names":[],"sources":["../../src/aggregation/aggregateResponses.ts"],"sourcesContent":["import type { Payload, PayloadRequest } from 'payload'\nimport { FORM_SUBMISSIONS_SLUG } from '../collections/formSubmissions'\nimport { FORMS_SLUG } from '../collections/forms'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { aggregateRowsForFields } from './aggregateRows'\nimport type { AggregationRow, FieldAggregation, FieldMeta, SubmissionStatusFilter } from './types'\n\nexport type AggregateFormResponsesArgs = {\n\tpayload: Payload\n\tformId: number | string\n\t/** Field machine names to aggregate. Defaults to every field that declares options (enumerable). */\n\tfields?: string[]\n\t/** Submission status to count. Defaults to `complete`. */\n\tstatus?: SubmissionStatusFilter\n\treq?: PayloadRequest\n\t/** Safety cap on submissions scanned; beyond it the result is flagged `truncated`. Default 10000. */\n\tmaxSubmissions?: number\n\t/** Page size for the submission scan. Default 500. */\n\tpageSize?: number\n}\n\nconst optionsOf = (field: FormFieldInstance): { value: string; label: string }[] | undefined => {\n\tif (!Array.isArray(field.options)) {\n\t\treturn undefined\n\t}\n\tconst options = (field.options as Array<{ label?: string; value?: string }>)\n\t\t.filter((option) => typeof option?.value === 'string')\n\t\t.map((option) => ({ value: String(option.value), label: option.label ?? String(option.value) }))\n\treturn options.length > 0 ? options : undefined\n}\n\n/** True when a field declares non-empty options (a choice field safe to aggregate publicly). */\nexport const fieldHasOptions = (field: FormFieldInstance): boolean => optionsOf(field) !== undefined\n\nconst metaFor = (field: FormFieldInstance): FieldMeta => ({\n\tfield: field.name,\n\tlabel: field.label ?? field.name,\n\tfieldType: field.blockType,\n\toptions: optionsOf(field),\n})\n\n/**\n * Aggregate submission responses for a form. Loads the form for current labels + option order, then pages\n * `payload.find` over its submissions (JSON `values` cannot be GROUP BY'd portably across Mongo + Postgres,\n * so we scan + reduce in JS, cross-DB-identically). Bounded by `maxSubmissions`; beyond it the result is\n * `truncated`. Returns one `FieldAggregation` per requested field (or per enumerable field by default).\n */\nexport const aggregateFormResponses = async (\n\targs: AggregateFormResponsesArgs\n): Promise<FieldAggregation[]> => {\n\tconst {\n\t\tpayload,\n\t\tformId,\n\t\tfields,\n\t\tstatus = 'complete',\n\t\treq,\n\t\tmaxSubmissions = 10000,\n\t\tpageSize = 500,\n\t} = args\n\tconst form = await payload\n\t\t.findByID({ collection: FORMS_SLUG, id: formId, depth: 0, overrideAccess: true, req })\n\t\t.catch(() => null)\n\tif (!form || !Array.isArray(form.fields)) {\n\t\treturn []\n\t}\n\tconst instances = form.fields as FormFieldInstance[]\n\tconst selected = fields\n\t\t? instances.filter((field) => fields.includes(field.name))\n\t\t: instances.filter((field) => optionsOf(field) !== undefined)\n\tif (selected.length === 0) {\n\t\treturn []\n\t}\n\tconst metas = selected.map(metaFor)\n\n\tconst statusWhere = status === 'all' ? [] : [{ status: { equals: status } }]\n\tconst where = { and: [{ form: { equals: formId } }, ...statusWhere] }\n\n\tconst rows: AggregationRow[] = []\n\tlet page = 1\n\tlet truncated = false\n\tfor (;;) {\n\t\tconst result = await payload.find({\n\t\t\tcollection: FORM_SUBMISSIONS_SLUG,\n\t\t\twhere,\n\t\t\tlimit: pageSize,\n\t\t\tpage,\n\t\t\tdepth: 0,\n\t\t\toverrideAccess: true,\n\t\t\treq,\n\t\t\tselect: { values: true, descriptors: true },\n\t\t})\n\t\tfor (const doc of result.docs as AggregationRow[]) {\n\t\t\t// Check before pushing so `truncated` means \"matching rows were left out\", not \"the cap was reached\n\t\t\t// exactly\": a form with precisely `maxSubmissions` responses is complete, not a sample.\n\t\t\tif (rows.length >= maxSubmissions) {\n\t\t\t\ttruncated = true\n\t\t\t\tbreak\n\t\t\t}\n\t\t\trows.push({ values: doc.values, descriptors: doc.descriptors })\n\t\t}\n\t\tif (truncated || !result.hasNextPage) {\n\t\t\tbreak\n\t\t}\n\t\tpage += 1\n\t}\n\n\treturn aggregateRowsForFields(rows, metas, truncated)\n}\n\nexport type AggregateFieldResponsesArgs = Omit<AggregateFormResponsesArgs, 'fields'> & {\n\tfield: string\n}\n\n/** Single-field convenience over `aggregateFormResponses`. Returns the field's aggregation, or null if absent. */\nexport const aggregateFieldResponses = async (\n\targs: AggregateFieldResponsesArgs\n): Promise<FieldAggregation | null> => {\n\tconst { field, ...rest } = args\n\tconst [result] = await aggregateFormResponses({ ...rest, fields: [field] })\n\treturn result ?? null\n}\n"],"mappings":";;;;AAqBA,MAAM,aAAa,UAA6E;CAC/F,IAAI,CAAC,MAAM,QAAQ,MAAM,OAAO,GAC/B;CAED,MAAM,UAAW,MAAM,QACrB,QAAQ,WAAW,OAAO,QAAQ,UAAU,QAAQ,EACpD,KAAK,YAAY;EAAE,OAAO,OAAO,OAAO,KAAK;EAAG,OAAO,OAAO,SAAS,OAAO,OAAO,KAAK;CAAE,EAAE;CAChG,OAAO,QAAQ,SAAS,IAAI,UAAU,KAAA;AACvC;;AAGA,MAAa,mBAAmB,UAAsC,UAAU,KAAK,MAAM,KAAA;AAE3F,MAAM,WAAW,WAAyC;CACzD,OAAO,MAAM;CACb,OAAO,MAAM,SAAS,MAAM;CAC5B,WAAW,MAAM;CACjB,SAAS,UAAU,KAAK;AACzB;;;;;;;AAQA,MAAa,yBAAyB,OACrC,SACiC;CACjC,MAAM,EACL,SACA,QACA,QACA,SAAS,YACT,KACA,iBAAiB,KACjB,WAAW,QACR;CACJ,MAAM,OAAO,MAAM,QACjB,SAAS;EAAE,YAAY;EAAY,IAAI;EAAQ,OAAO;EAAG,gBAAgB;EAAM;CAAI,CAAC,EACpF,YAAY,IAAI;CAClB,IAAI,CAAC,QAAQ,CAAC,MAAM,QAAQ,KAAK,MAAM,GACtC,OAAO,CAAC;CAET,MAAM,YAAY,KAAK;CACvB,MAAM,WAAW,SACd,UAAU,QAAQ,UAAU,OAAO,SAAS,MAAM,IAAI,CAAC,IACvD,UAAU,QAAQ,UAAU,UAAU,KAAK,MAAM,KAAA,CAAS;CAC7D,IAAI,SAAS,WAAW,GACvB,OAAO,CAAC;CAET,MAAM,QAAQ,SAAS,IAAI,OAAO;CAGlC,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,OAAO,EAAE,GAAG,GADhC,WAAW,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,OAAO,EAAE,CAAC,CACT,EAAE;CAEpE,MAAM,OAAyB,CAAC;CAChC,IAAI,OAAO;CACX,IAAI,YAAY;CAChB,SAAS;EACR,MAAM,SAAS,MAAM,QAAQ,KAAK;GACjC,YAAY;GACZ;GACA,OAAO;GACP;GACA,OAAO;GACP,gBAAgB;GAChB;GACA,QAAQ;IAAE,QAAQ;IAAM,aAAa;GAAK;EAC3C,CAAC;EACD,KAAK,MAAM,OAAO,OAAO,MAA0B;GAGlD,IAAI,KAAK,UAAU,gBAAgB;IAClC,YAAY;IACZ;GACD;GACA,KAAK,KAAK;IAAE,QAAQ,IAAI;IAAQ,aAAa,IAAI;GAAY,CAAC;EAC/D;EACA,IAAI,aAAa,CAAC,OAAO,aACxB;EAED,QAAQ;CACT;CAEA,OAAO,uBAAuB,MAAM,OAAO,SAAS;AACrD;;AAOA,MAAa,0BAA0B,OACtC,SACsC;CACtC,MAAM,EAAE,OAAO,GAAG,SAAS;CAC3B,MAAM,CAAC,UAAU,MAAM,uBAAuB;EAAE,GAAG;EAAM,QAAQ,CAAC,KAAK;CAAE,CAAC;CAC1E,OAAO,UAAU;AAClB"}

package/dist/aggregation/aggregateRows.d.ts

@@ -0,0 +1,10 @@
+import { AggregationRow, FieldAggregation, FieldMeta } from "./types.js";
+
+//#region src/aggregation/aggregateRows.d.ts
+/** Aggregate one field across rows: respondent-denominated counts + percentages, option-ordered. */
+declare const aggregateRowForField: (rows: AggregationRow[], meta: FieldMeta, truncated: boolean) => FieldAggregation;
+/** Aggregate several fields across the same set of rows. */
+declare const aggregateRowsForFields: (rows: AggregationRow[], metas: FieldMeta[], truncated: boolean) => FieldAggregation[];
+//#endregion
+export { aggregateRowForField, aggregateRowsForFields };
+//# sourceMappingURL=aggregateRows.d.ts.map

package/dist/aggregation/aggregateRows.js

@@ -0,0 +1,64 @@
+//#region src/aggregation/aggregateRows.ts
+const round1 = (n) => Math.round(n * 10) / 10;
+/** The grouping keys a single answer contributes: [] for empty, one per element for arrays, else one. */
+const valueKeys = (value) => {
+	if (value == null || value === "") return [];
+	if (Array.isArray(value)) return value.filter((entry) => entry != null && entry !== "").map((entry) => String(entry));
+	return [String(value)];
+};
+/** Merge every row's descriptor snapshot for one field into a value -> label map (last write wins). */
+const snapshotLabels = (rows, field) => {
+	const labels = /* @__PURE__ */ new Map();
+	for (const row of rows) for (const descriptor of row.descriptors ?? []) if (descriptor.field === field && descriptor.optionLabels) for (const [value, label] of Object.entries(descriptor.optionLabels)) labels.set(value, label);
+	return labels;
+};
+/** Aggregate one field across rows: respondent-denominated counts + percentages, option-ordered. */
+const aggregateRowForField = (rows, meta, truncated) => {
+	const counts = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const option of meta.options ?? []) {
+		counts.set(option.value, 0);
+		order.push(option.value);
+	}
+	const snapshots = snapshotLabels(rows, meta.field);
+	let total = 0;
+	for (const row of rows) {
+		const keys = valueKeys((row.values ?? []).find((entry) => entry.field === meta.field)?.value);
+		if (keys.length === 0) continue;
+		total += 1;
+		for (const key of keys) {
+			if (!counts.has(key)) {
+				counts.set(key, 0);
+				order.push(key);
+			}
+			counts.set(key, (counts.get(key) ?? 0) + 1);
+		}
+	}
+	const optionValues = new Set((meta.options ?? []).map((option) => option.value));
+	const leftovers = order.filter((value) => !optionValues.has(value)).sort((a, b) => (counts.get(b) ?? 0) - (counts.get(a) ?? 0));
+	const ordered = [...(meta.options ?? []).map((option) => option.value), ...leftovers];
+	const optionLabelByValue = new Map((meta.options ?? []).map((option) => [option.value, option.label]));
+	const buckets = ordered.map((value) => {
+		const count = counts.get(value) ?? 0;
+		return {
+			value,
+			label: optionLabelByValue.get(value) ?? snapshots.get(value) ?? value,
+			count,
+			percentage: total > 0 ? round1(count / total * 100) : 0
+		};
+	});
+	return {
+		field: meta.field,
+		label: meta.label,
+		fieldType: meta.fieldType,
+		total,
+		buckets,
+		truncated
+	};
+};
+/** Aggregate several fields across the same set of rows. */
+const aggregateRowsForFields = (rows, metas, truncated) => metas.map((meta) => aggregateRowForField(rows, meta, truncated));
+//#endregion
+export { aggregateRowForField, aggregateRowsForFields };
+
+//# sourceMappingURL=aggregateRows.js.map

package/dist/aggregation/aggregateRows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregateRows.js","names":[],"sources":["../../src/aggregation/aggregateRows.ts"],"sourcesContent":["import type { AggregationBucket, AggregationRow, FieldAggregation, FieldMeta } from './types'\n\nconst round1 = (n: number): number => Math.round(n * 10) / 10\n\n/** The grouping keys a single answer contributes: [] for empty, one per element for arrays, else one. */\nconst valueKeys = (value: unknown): string[] => {\n\tif (value == null || value === '') {\n\t\treturn []\n\t}\n\tif (Array.isArray(value)) {\n\t\treturn value.filter((entry) => entry != null && entry !== '').map((entry) => String(entry))\n\t}\n\treturn [String(value)]\n}\n\n/** Merge every row's descriptor snapshot for one field into a value -> label map (last write wins). */\nconst snapshotLabels = (rows: AggregationRow[], field: string): Map<string, string> => {\n\tconst labels = new Map<string, string>()\n\tfor (const row of rows) {\n\t\tfor (const descriptor of row.descriptors ?? []) {\n\t\t\tif (descriptor.field === field && descriptor.optionLabels) {\n\t\t\t\tfor (const [value, label] of Object.entries(descriptor.optionLabels)) {\n\t\t\t\t\tlabels.set(value, label)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\treturn labels\n}\n\n/** Aggregate one field across rows: respondent-denominated counts + percentages, option-ordered. */\nexport const aggregateRowForField = (\n\trows: AggregationRow[],\n\tmeta: FieldMeta,\n\ttruncated: boolean\n): FieldAggregation => {\n\tconst counts = new Map<string, number>()\n\tconst order: string[] = []\n\tfor (const option of meta.options ?? []) {\n\t\tcounts.set(option.value, 0)\n\t\torder.push(option.value)\n\t}\n\tconst snapshots = snapshotLabels(rows, meta.field)\n\tlet total = 0\n\tfor (const row of rows) {\n\t\tconst answer = (row.values ?? []).find((entry) => entry.field === meta.field)\n\t\tconst keys = valueKeys(answer?.value)\n\t\tif (keys.length === 0) {\n\t\t\tcontinue\n\t\t}\n\t\ttotal += 1\n\t\tfor (const key of keys) {\n\t\t\tif (!counts.has(key)) {\n\t\t\t\tcounts.set(key, 0)\n\t\t\t\torder.push(key)\n\t\t\t}\n\t\t\tcounts.set(key, (counts.get(key) ?? 0) + 1)\n\t\t}\n\t}\n\n\tconst optionValues = new Set((meta.options ?? []).map((option) => option.value))\n\tconst leftovers = order\n\t\t.filter((value) => !optionValues.has(value))\n\t\t.sort((a, b) => (counts.get(b) ?? 0) - (counts.get(a) ?? 0))\n\tconst ordered = [...(meta.options ?? []).map((option) => option.value), ...leftovers]\n\n\tconst optionLabelByValue = new Map(\n\t\t(meta.options ?? []).map((option) => [option.value, option.label])\n\t)\n\tconst buckets: AggregationBucket[] = ordered.map((value) => {\n\t\tconst count = counts.get(value) ?? 0\n\t\treturn {\n\t\t\tvalue,\n\t\t\tlabel: optionLabelByValue.get(value) ?? snapshots.get(value) ?? value,\n\t\t\tcount,\n\t\t\tpercentage: total > 0 ? round1((count / total) * 100) : 0,\n\t\t}\n\t})\n\n\treturn {\n\t\tfield: meta.field,\n\t\tlabel: meta.label,\n\t\tfieldType: meta.fieldType,\n\t\ttotal,\n\t\tbuckets,\n\t\ttruncated,\n\t}\n}\n\n/** Aggregate several fields across the same set of rows. */\nexport const aggregateRowsForFields = (\n\trows: AggregationRow[],\n\tmetas: FieldMeta[],\n\ttruncated: boolean\n): FieldAggregation[] => metas.map((meta) => aggregateRowForField(rows, meta, truncated))\n"],"mappings":";AAEA,MAAM,UAAU,MAAsB,KAAK,MAAM,IAAI,EAAE,IAAI;;AAG3D,MAAM,aAAa,UAA6B;CAC/C,IAAI,SAAS,QAAQ,UAAU,IAC9B,OAAO,CAAC;CAET,IAAI,MAAM,QAAQ,KAAK,GACtB,OAAO,MAAM,QAAQ,UAAU,SAAS,QAAQ,UAAU,EAAE,EAAE,KAAK,UAAU,OAAO,KAAK,CAAC;CAE3F,OAAO,CAAC,OAAO,KAAK,CAAC;AACtB;;AAGA,MAAM,kBAAkB,MAAwB,UAAuC;CACtF,MAAM,yBAAS,IAAI,IAAoB;CACvC,KAAK,MAAM,OAAO,MACjB,KAAK,MAAM,cAAc,IAAI,eAAe,CAAC,GAC5C,IAAI,WAAW,UAAU,SAAS,WAAW,cAC5C,KAAK,MAAM,CAAC,OAAO,UAAU,OAAO,QAAQ,WAAW,YAAY,GAClE,OAAO,IAAI,OAAO,KAAK;CAK3B,OAAO;AACR;;AAGA,MAAa,wBACZ,MACA,MACA,cACsB;CACtB,MAAM,yBAAS,IAAI,IAAoB;CACvC,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,UAAU,KAAK,WAAW,CAAC,GAAG;EACxC,OAAO,IAAI,OAAO,OAAO,CAAC;EAC1B,MAAM,KAAK,OAAO,KAAK;CACxB;CACA,MAAM,YAAY,eAAe,MAAM,KAAK,KAAK;CACjD,IAAI,QAAQ;CACZ,KAAK,MAAM,OAAO,MAAM;EAEvB,MAAM,OAAO,WADG,IAAI,UAAU,CAAC,GAAG,MAAM,UAAU,MAAM,UAAU,KAAK,KAC3C,GAAG,KAAK;EACpC,IAAI,KAAK,WAAW,GACnB;EAED,SAAS;EACT,KAAK,MAAM,OAAO,MAAM;GACvB,IAAI,CAAC,OAAO,IAAI,GAAG,GAAG;IACrB,OAAO,IAAI,KAAK,CAAC;IACjB,MAAM,KAAK,GAAG;GACf;GACA,OAAO,IAAI,MAAM,OAAO,IAAI,GAAG,KAAK,KAAK,CAAC;EAC3C;CACD;CAEA,MAAM,eAAe,IAAI,KAAK,KAAK,WAAW,CAAC,GAAG,KAAK,WAAW,OAAO,KAAK,CAAC;CAC/E,MAAM,YAAY,MAChB,QAAQ,UAAU,CAAC,aAAa,IAAI,KAAK,CAAC,EAC1C,MAAM,GAAG,OAAO,OAAO,IAAI,CAAC,KAAK,MAAM,OAAO,IAAI,CAAC,KAAK,EAAE;CAC5D,MAAM,UAAU,CAAC,IAAI,KAAK,WAAW,CAAC,GAAG,KAAK,WAAW,OAAO,KAAK,GAAG,GAAG,SAAS;CAEpF,MAAM,qBAAqB,IAAI,KAC7B,KAAK,WAAW,CAAC,GAAG,KAAK,WAAW,CAAC,OAAO,OAAO,OAAO,KAAK,CAAC,CAClE;CACA,MAAM,UAA+B,QAAQ,KAAK,UAAU;EAC3D,MAAM,QAAQ,OAAO,IAAI,KAAK,KAAK;EACnC,OAAO;GACN;GACA,OAAO,mBAAmB,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK;GAChE;GACA,YAAY,QAAQ,IAAI,OAAQ,QAAQ,QAAS,GAAG,IAAI;EACzD;CACD,CAAC;CAED,OAAO;EACN,OAAO,KAAK;EACZ,OAAO,KAAK;EACZ,WAAW,KAAK;EAChB;EACA;EACA;CACD;AACD;;AAGA,MAAa,0BACZ,MACA,OACA,cACwB,MAAM,KAAK,SAAS,qBAAqB,MAAM,MAAM,SAAS,CAAC"}

package/dist/aggregation/resolveResultsRequest.d.ts

@@ -0,0 +1,32 @@
+import { FieldAggregation } from "./types.js";
+import { Payload, PayloadRequest } from "payload";
+
+//#region src/aggregation/resolveResultsRequest.d.ts
+type ResolveResultsRequestArgs = {
+  payload: Payload;
+  formId: number | string | undefined; /** The requested field (query param). */
+  field?: string; /** Whether the caller is authenticated (an admin/user). */
+  isAuthed: boolean;
+  req?: PayloadRequest;
+};
+type ResolveResultsRequestResult = {
+  status: number;
+  body: {
+    results: FieldAggregation[];
+  } | {
+    errors: {
+      message: string;
+    }[];
+  };
+};
+/**
+ * Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all
+ * enumerable fields). Anonymous callers are allowed only when the form opted in (`showResults`), and then
+ * only for the configured `resultsField`, and only if that field is enumerable (has options) so a
+ * misconfigured `resultsField` pointing at a free-text or PII field can never be dumped publicly. Returns
+ * only aggregate counts, never raw submissions.
+ */
+declare const resolveFormResultsRequest: (args: ResolveResultsRequestArgs) => Promise<ResolveResultsRequestResult>;
+//#endregion
+export { ResolveResultsRequestArgs, ResolveResultsRequestResult, resolveFormResultsRequest };
+//# sourceMappingURL=resolveResultsRequest.d.ts.map

package/dist/aggregation/resolveResultsRequest.js

@@ -0,0 +1,56 @@
+import { aggregateFormResponses, fieldHasOptions } from "./aggregateResponses.js";
+import { FORMS_SLUG } from "../collections/forms.js";
+//#region src/aggregation/resolveResultsRequest.ts
+const forbidden = {
+	status: 403,
+	body: { errors: [{ message: "Forbidden" }] }
+};
+/**
+* Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all
+* enumerable fields). Anonymous callers are allowed only when the form opted in (`showResults`), and then
+* only for the configured `resultsField`, and only if that field is enumerable (has options) so a
+* misconfigured `resultsField` pointing at a free-text or PII field can never be dumped publicly. Returns
+* only aggregate counts, never raw submissions.
+*/
+const resolveFormResultsRequest = async (args) => {
+	const { payload, formId, field, isAuthed, req } = args;
+	if (formId == null) return {
+		status: 400,
+		body: { errors: [{ message: "Missing form id" }] }
+	};
+	const form = await payload.findByID({
+		collection: FORMS_SLUG,
+		id: formId,
+		depth: 0,
+		overrideAccess: true,
+		req
+	}).catch(() => null);
+	if (!form) return {
+		status: 404,
+		body: { errors: [{ message: "Not found" }] }
+	};
+	let fields;
+	if (isAuthed) fields = field ? [field] : void 0;
+	else {
+		if (form.showResults !== true) return forbidden;
+		const publicField = typeof form.resultsField === "string" && form.resultsField.length > 0 ? form.resultsField : void 0;
+		if (!publicField) return forbidden;
+		if (field && field !== publicField) return forbidden;
+		const instance = (Array.isArray(form.fields) ? form.fields : []).find((entry) => entry.name === publicField);
+		if (!instance || !fieldHasOptions(instance)) return forbidden;
+		fields = [publicField];
+	}
+	return {
+		status: 200,
+		body: { results: await aggregateFormResponses({
+			payload,
+			formId,
+			fields,
+			req
+		}) }
+	};
+};
+//#endregion
+export { resolveFormResultsRequest };
+
+//# sourceMappingURL=resolveResultsRequest.js.map

package/dist/aggregation/resolveResultsRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveResultsRequest.js","names":[],"sources":["../../src/aggregation/resolveResultsRequest.ts"],"sourcesContent":["import type { Payload, PayloadRequest } from 'payload'\nimport { FORMS_SLUG } from '../collections/forms'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { aggregateFormResponses, fieldHasOptions } from './aggregateResponses'\nimport type { FieldAggregation } from './types'\n\nexport type ResolveResultsRequestArgs = {\n\tpayload: Payload\n\tformId: number | string | undefined\n\t/** The requested field (query param). */\n\tfield?: string\n\t/** Whether the caller is authenticated (an admin/user). */\n\tisAuthed: boolean\n\treq?: PayloadRequest\n}\n\nexport type ResolveResultsRequestResult = {\n\tstatus: number\n\tbody: { results: FieldAggregation[] } | { errors: { message: string }[] }\n}\n\nconst forbidden: ResolveResultsRequestResult = {\n\tstatus: 403,\n\tbody: { errors: [{ message: 'Forbidden' }] },\n}\n\n/**\n * Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all\n * enumerable fields). Anonymous callers are allowed only when the form opted in (`showResults`), and then\n * only for the configured `resultsField`, and only if that field is enumerable (has options) so a\n * misconfigured `resultsField` pointing at a free-text or PII field can never be dumped publicly. Returns\n * only aggregate counts, never raw submissions.\n */\nexport const resolveFormResultsRequest = async (\n\targs: ResolveResultsRequestArgs\n): Promise<ResolveResultsRequestResult> => {\n\tconst { payload, formId, field, isAuthed, req } = args\n\tif (formId == null) {\n\t\treturn { status: 400, body: { errors: [{ message: 'Missing form id' }] } }\n\t}\n\tconst form = await payload\n\t\t.findByID({ collection: FORMS_SLUG, id: formId, depth: 0, overrideAccess: true, req })\n\t\t.catch(() => null)\n\tif (!form) {\n\t\treturn { status: 404, body: { errors: [{ message: 'Not found' }] } }\n\t}\n\n\tlet fields: string[] | undefined\n\tif (isAuthed) {\n\t\tfields = field ? [field] : undefined\n\t} else {\n\t\tif (form.showResults !== true) {\n\t\t\treturn forbidden\n\t\t}\n\t\tconst publicField =\n\t\t\ttypeof form.resultsField === 'string' && form.resultsField.length > 0\n\t\t\t\t? form.resultsField\n\t\t\t\t: undefined\n\t\tif (!publicField) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (field && field !== publicField) {\n\t\t\treturn forbidden\n\t\t}\n\t\tconst instances = Array.isArray(form.fields) ? (form.fields as FormFieldInstance[]) : []\n\t\tconst instance = instances.find((entry) => entry.name === publicField)\n\t\tif (!instance || !fieldHasOptions(instance)) {\n\t\t\treturn forbidden\n\t\t}\n\t\tfields = [publicField]\n\t}\n\n\tconst results = await aggregateFormResponses({ payload, formId, fields, req })\n\treturn { status: 200, body: { results } }\n}\n"],"mappings":";;;AAqBA,MAAM,YAAyC;CAC9C,QAAQ;CACR,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,EAAE;AAC5C;;;;;;;;AASA,MAAa,4BAA4B,OACxC,SAC0C;CAC1C,MAAM,EAAE,SAAS,QAAQ,OAAO,UAAU,QAAQ;CAClD,IAAI,UAAU,MACb,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,kBAAkB,CAAC,EAAE;CAAE;CAE1E,MAAM,OAAO,MAAM,QACjB,SAAS;EAAE,YAAY;EAAY,IAAI;EAAQ,OAAO;EAAG,gBAAgB;EAAM;CAAI,CAAC,EACpF,YAAY,IAAI;CAClB,IAAI,CAAC,MACJ,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,EAAE;CAAE;CAGpE,IAAI;CACJ,IAAI,UACH,SAAS,QAAQ,CAAC,KAAK,IAAI,KAAA;MACrB;EACN,IAAI,KAAK,gBAAgB,MACxB,OAAO;EAER,MAAM,cACL,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAa,SAAS,IACjE,KAAK,eACL,KAAA;EACJ,IAAI,CAAC,aACJ,OAAO;EAER,IAAI,SAAS,UAAU,aACtB,OAAO;EAGR,MAAM,YADY,MAAM,QAAQ,KAAK,MAAM,IAAK,KAAK,SAAiC,CAAC,GAC5D,MAAM,UAAU,MAAM,SAAS,WAAW;EACrE,IAAI,CAAC,YAAY,CAAC,gBAAgB,QAAQ,GACzC,OAAO;EAER,SAAS,CAAC,WAAW;CACtB;CAGA,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,SAAA,MADR,uBAAuB;GAAE;GAAS;GAAQ;GAAQ;EAAI,CAAC,EACvC;CAAE;AACzC"}

package/dist/aggregation/types.d.ts

@@ -0,0 +1,39 @@
+import { SubmissionDescriptor, SubmissionValue } from "../submissions/types.js";
+
+//#region src/aggregation/types.d.ts
+/** Which submission statuses to count. `complete` (default) excludes partials; `all` counts everything. */
+type SubmissionStatusFilter = 'complete' | 'partial' | 'all';
+/** One answer option (or distinct value) with its tally. */
+type AggregationBucket = {
+  /** The answer value, stringified (the grouping key). */value: string; /** Display label: current option label, else the submitted snapshot label, else the raw value. */
+  label: string;
+  count: number; /** Share of respondents, 0-100, rounded to one decimal. Can sum past 100 for multi-value fields. */
+  percentage: number;
+};
+/** Aggregated responses for one field across a form's submissions. */
+type FieldAggregation = {
+  field: string;
+  label?: string;
+  fieldType?: string; /** Respondents: submissions with a non-empty answer for this field. The percentage denominator. */
+  total: number;
+  buckets: AggregationBucket[]; /** True when the `maxSubmissions` cap was hit, so the tallies are a (large) sample, not the full set. */
+  truncated: boolean;
+};
+/** The slice of a submission the reducer reads. */
+type AggregationRow = {
+  values?: SubmissionValue[];
+  descriptors?: SubmissionDescriptor[];
+};
+/** Field metadata the reducer needs to label and order buckets, derived from the live form definition. */
+type FieldMeta = {
+  field: string;
+  label?: string;
+  fieldType?: string; /** Ordered known options with current labels; drives bucket order and label resolution. */
+  options?: {
+    value: string;
+    label: string;
+  }[];
+};
+//#endregion
+export { AggregationBucket, AggregationRow, FieldAggregation, FieldMeta, SubmissionStatusFilter };
+//# sourceMappingURL=types.d.ts.map

package/dist/calc/computeCalcFields.d.ts

@@ -0,0 +1,15 @@
+import { FormFieldInstance } from "../submissions/types.js";
+import { CalcExpression } from "./types.js";
+
+//#region src/calc/computeCalcFields.d.ts
+/** Returns the calc expression if the field carries one (non-null object), otherwise undefined. */
+declare const calcExpressionOf: (field: FormFieldInstance) => CalcExpression | undefined;
+/**
+ * Returns answers with every calc field's value derived from its expression,
+ * folded in declaration order so a calc may reference an earlier calc's result.
+ * Identity when no field carries an expression.
+ */
+declare const computeCalcFields: (fields: FormFieldInstance[], answers: Record<string, unknown>) => Record<string, unknown>;
+//#endregion
+export { calcExpressionOf, computeCalcFields };
+//# sourceMappingURL=computeCalcFields.d.ts.map

package/dist/calc/computeCalcFields.js

@@ -0,0 +1,27 @@
+import { evaluateCalc } from "./evaluate.js";
+//#region src/calc/computeCalcFields.ts
+/** Returns the calc expression if the field carries one (non-null object), otherwise undefined. */
+const calcExpressionOf = (field) => {
+	const expr = field.expression;
+	return expr !== null && typeof expr === "object" && !Array.isArray(expr) ? expr : void 0;
+};
+/**
+* Returns answers with every calc field's value derived from its expression,
+* folded in declaration order so a calc may reference an earlier calc's result.
+* Identity when no field carries an expression.
+*/
+const computeCalcFields = (fields, answers) => {
+	let next = answers;
+	for (const field of fields) {
+		const expr = calcExpressionOf(field);
+		if (expr) next = {
+			...next,
+			[field.name]: evaluateCalc(expr, next)
+		};
+	}
+	return next;
+};
+//#endregion
+export { calcExpressionOf, computeCalcFields };
+
+//# sourceMappingURL=computeCalcFields.js.map

package/dist/calc/computeCalcFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computeCalcFields.js","names":[],"sources":["../../src/calc/computeCalcFields.ts"],"sourcesContent":["import type { FormFieldInstance } from '../submissions/types'\nimport { evaluateCalc } from './evaluate'\nimport type { CalcExpression } from './types'\n\n/** Returns the calc expression if the field carries one (non-null object), otherwise undefined. */\nexport const calcExpressionOf = (field: FormFieldInstance): CalcExpression | undefined => {\n\tconst expr = field.expression\n\treturn expr !== null && typeof expr === 'object' && !Array.isArray(expr)\n\t\t? (expr as CalcExpression)\n\t\t: undefined\n}\n\n/**\n * Returns answers with every calc field's value derived from its expression,\n * folded in declaration order so a calc may reference an earlier calc's result.\n * Identity when no field carries an expression.\n */\nexport const computeCalcFields = (\n\tfields: FormFieldInstance[],\n\tanswers: Record<string, unknown>\n): Record<string, unknown> => {\n\tlet next = answers\n\tfor (const field of fields) {\n\t\tconst expr = calcExpressionOf(field)\n\t\tif (expr) {\n\t\t\tnext = { ...next, [field.name]: evaluateCalc(expr, next) }\n\t\t}\n\t}\n\treturn next\n}\n"],"mappings":";;;AAKA,MAAa,oBAAoB,UAAyD;CACzF,MAAM,OAAO,MAAM;CACnB,OAAO,SAAS,QAAQ,OAAO,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,IACnE,OACD,KAAA;AACJ;;;;;;AAOA,MAAa,qBACZ,QACA,YAC6B;CAC7B,IAAI,OAAO;CACX,KAAK,MAAM,SAAS,QAAQ;EAC3B,MAAM,OAAO,iBAAiB,KAAK;EACnC,IAAI,MACH,OAAO;GAAE,GAAG;IAAO,MAAM,OAAO,aAAa,MAAM,IAAI;EAAE;CAE3D;CACA,OAAO;AACR"}

package/dist/calc/evaluate.d.ts

@@ -0,0 +1,8 @@
+import { CalcExpression } from "./types.js";
+
+//#region src/calc/evaluate.d.ts
+/** Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). */
+declare const evaluateCalc: (expr: CalcExpression | null | undefined, answers: Record<string, unknown>) => number;
+//#endregion
+export { evaluateCalc };
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/calc/evaluate.js

@@ -0,0 +1,59 @@
+//#region src/calc/evaluate.ts
+const MAX_DEPTH = 64;
+const toNumber = (value) => {
+	if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+	if (typeof value === "string" && value.trim() !== "") {
+		const n = Number(value);
+		return Number.isFinite(n) ? n : 0;
+	}
+	return 0;
+};
+const finite = (n) => Number.isFinite(n) ? n : 0;
+const FUNCTIONS = {
+	min: (a) => a.length ? Math.min(...a) : 0,
+	max: (a) => a.length ? Math.max(...a) : 0,
+	round: (a) => Math.round(a[0] ?? 0),
+	abs: (a) => Math.abs(a[0] ?? 0),
+	ceil: (a) => Math.ceil(a[0] ?? 0),
+	floor: (a) => Math.floor(a[0] ?? 0)
+};
+const evalNode = (expr, answers, depth) => {
+	if (depth > MAX_DEPTH || expr == null || typeof expr !== "object") return 0;
+	switch (expr.type) {
+		case "lit": return finite(toNumber(expr.value));
+		case "ref": return toNumber(answers[expr.field]);
+		case "neg": return finite(-evalNode(expr.operand, answers, depth + 1));
+		case "op": {
+			const l = evalNode(expr.left, answers, depth + 1);
+			const r = evalNode(expr.right, answers, depth + 1);
+			switch (expr.op) {
+				case "+": return finite(l + r);
+				case "-": return finite(l - r);
+				case "*": return finite(l * r);
+				case "/": return r === 0 ? 0 : finite(l / r);
+				case "%": return r === 0 ? 0 : finite(l % r);
+				default: return 0;
+			}
+		}
+		case "fn": {
+			const fn = FUNCTIONS[expr.fn];
+			if (!fn) return 0;
+			return finite(fn(Array.isArray(expr.args) ? expr.args.map((a) => evalNode(a, answers, depth + 1)) : []));
+		}
+		case "weight": {
+			const weights = expr.weights ?? {};
+			const value = answers[expr.field];
+			return finite((Array.isArray(value) ? value : value == null || value === "" ? [] : [value]).reduce((sum, v) => sum + toNumber(weights[String(v)]), 0));
+		}
+		default: return 0;
+	}
+};
+/** Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). */
+const evaluateCalc = (expr, answers) => {
+	if (!expr) return 0;
+	return evalNode(expr, answers, 0);
+};
+//#endregion
+export { evaluateCalc };
+
+//# sourceMappingURL=evaluate.js.map

package/dist/calc/evaluate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.js","names":[],"sources":["../../src/calc/evaluate.ts"],"sourcesContent":["import type { CalcExpression } from './types'\n\nconst MAX_DEPTH = 64\n\nconst toNumber = (value: unknown): number => {\n\tif (typeof value === 'number') {\n\t\treturn Number.isFinite(value) ? value : 0\n\t}\n\tif (typeof value === 'string' && value.trim() !== '') {\n\t\tconst n = Number(value)\n\t\treturn Number.isFinite(n) ? n : 0\n\t}\n\treturn 0\n}\n\nconst finite = (n: number): number => (Number.isFinite(n) ? n : 0)\n\nconst FUNCTIONS: Record<string, (args: number[]) => number> = {\n\tmin: (a) => (a.length ? Math.min(...a) : 0),\n\tmax: (a) => (a.length ? Math.max(...a) : 0),\n\tround: (a) => Math.round(a[0] ?? 0),\n\tabs: (a) => Math.abs(a[0] ?? 0),\n\tceil: (a) => Math.ceil(a[0] ?? 0),\n\tfloor: (a) => Math.floor(a[0] ?? 0),\n}\n\nconst evalNode = (\n\texpr: CalcExpression,\n\tanswers: Record<string, unknown>,\n\tdepth: number\n): number => {\n\tif (depth > MAX_DEPTH || expr == null || typeof expr !== 'object') {\n\t\treturn 0\n\t}\n\tswitch (expr.type) {\n\t\tcase 'lit':\n\t\t\treturn finite(toNumber(expr.value))\n\t\tcase 'ref':\n\t\t\treturn toNumber(answers[expr.field])\n\t\tcase 'neg':\n\t\t\treturn finite(-evalNode(expr.operand, answers, depth + 1))\n\t\tcase 'op': {\n\t\t\tconst l = evalNode(expr.left, answers, depth + 1)\n\t\t\tconst r = evalNode(expr.right, answers, depth + 1)\n\t\t\tswitch (expr.op) {\n\t\t\t\tcase '+':\n\t\t\t\t\treturn finite(l + r)\n\t\t\t\tcase '-':\n\t\t\t\t\treturn finite(l - r)\n\t\t\t\tcase '*':\n\t\t\t\t\treturn finite(l * r)\n\t\t\t\tcase '/':\n\t\t\t\t\treturn r === 0 ? 0 : finite(l / r)\n\t\t\t\tcase '%':\n\t\t\t\t\treturn r === 0 ? 0 : finite(l % r)\n\t\t\t\tdefault:\n\t\t\t\t\treturn 0\n\t\t\t}\n\t\t}\n\t\tcase 'fn': {\n\t\t\tconst fn = FUNCTIONS[expr.fn]\n\t\t\tif (!fn) {\n\t\t\t\treturn 0\n\t\t\t}\n\t\t\tconst args = Array.isArray(expr.args)\n\t\t\t\t? expr.args.map((a) => evalNode(a, answers, depth + 1))\n\t\t\t\t: []\n\t\t\treturn finite(fn(args))\n\t\t}\n\t\tcase 'weight': {\n\t\t\tconst weights = expr.weights ?? {}\n\t\t\tconst value = answers[expr.field]\n\t\t\tconst chosen = Array.isArray(value) ? value : value == null || value === '' ? [] : [value]\n\t\t\treturn finite(\n\t\t\t\tchosen.reduce((sum: number, v: unknown) => sum + toNumber(weights[String(v)]), 0)\n\t\t\t)\n\t\t}\n\t\tdefault:\n\t\t\treturn 0\n\t}\n}\n\n/** Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). */\nexport const evaluateCalc = (\n\texpr: CalcExpression | null | undefined,\n\tanswers: Record<string, unknown>\n): number => {\n\tif (!expr) {\n\t\treturn 0\n\t}\n\treturn evalNode(expr, answers, 0)\n}\n"],"mappings":";AAEA,MAAM,YAAY;AAElB,MAAM,YAAY,UAA2B;CAC5C,IAAI,OAAO,UAAU,UACpB,OAAO,OAAO,SAAS,KAAK,IAAI,QAAQ;CAEzC,IAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,IAAI;EACrD,MAAM,IAAI,OAAO,KAAK;EACtB,OAAO,OAAO,SAAS,CAAC,IAAI,IAAI;CACjC;CACA,OAAO;AACR;AAEA,MAAM,UAAU,MAAuB,OAAO,SAAS,CAAC,IAAI,IAAI;AAEhE,MAAM,YAAwD;CAC7D,MAAM,MAAO,EAAE,SAAS,KAAK,IAAI,GAAG,CAAC,IAAI;CACzC,MAAM,MAAO,EAAE,SAAS,KAAK,IAAI,GAAG,CAAC,IAAI;CACzC,QAAQ,MAAM,KAAK,MAAM,EAAE,MAAM,CAAC;CAClC,MAAM,MAAM,KAAK,IAAI,EAAE,MAAM,CAAC;CAC9B,OAAO,MAAM,KAAK,KAAK,EAAE,MAAM,CAAC;CAChC,QAAQ,MAAM,KAAK,MAAM,EAAE,MAAM,CAAC;AACnC;AAEA,MAAM,YACL,MACA,SACA,UACY;CACZ,IAAI,QAAQ,aAAa,QAAQ,QAAQ,OAAO,SAAS,UACxD,OAAO;CAER,QAAQ,KAAK,MAAb;EACC,KAAK,OACJ,OAAO,OAAO,SAAS,KAAK,KAAK,CAAC;EACnC,KAAK,OACJ,OAAO,SAAS,QAAQ,KAAK,MAAM;EACpC,KAAK,OACJ,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS,SAAS,QAAQ,CAAC,CAAC;EAC1D,KAAK,MAAM;GACV,MAAM,IAAI,SAAS,KAAK,MAAM,SAAS,QAAQ,CAAC;GAChD,MAAM,IAAI,SAAS,KAAK,OAAO,SAAS,QAAQ,CAAC;GACjD,QAAQ,KAAK,IAAb;IACC,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,MAAM,IAAI,IAAI,OAAO,IAAI,CAAC;IAClC,KAAK,KACJ,OAAO,MAAM,IAAI,IAAI,OAAO,IAAI,CAAC;IAClC,SACC,OAAO;GACT;EACD;EACA,KAAK,MAAM;GACV,MAAM,KAAK,UAAU,KAAK;GAC1B,IAAI,CAAC,IACJ,OAAO;GAKR,OAAO,OAAO,GAHD,MAAM,QAAQ,KAAK,IAAI,IACjC,KAAK,KAAK,KAAK,MAAM,SAAS,GAAG,SAAS,QAAQ,CAAC,CAAC,IACpD,CAAC,CACiB,CAAC;EACvB;EACA,KAAK,UAAU;GACd,MAAM,UAAU,KAAK,WAAW,CAAC;GACjC,MAAM,QAAQ,QAAQ,KAAK;GAE3B,OAAO,QADQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,SAAS,QAAQ,UAAU,KAAK,CAAC,IAAI,CAAC,KAAK,GAEjF,QAAQ,KAAa,MAAe,MAAM,SAAS,QAAQ,OAAO,CAAC,EAAE,GAAG,CAAC,CACjF;EACD;EACA,SACC,OAAO;CACT;AACD;;AAGA,MAAa,gBACZ,MACA,YACY;CACZ,IAAI,CAAC,MACJ,OAAO;CAER,OAAO,SAAS,MAAM,SAAS,CAAC;AACjC"}

package/dist/calc/normalizeCalc.d.ts

@@ -0,0 +1,8 @@
+import { CalcExpression } from "./types.js";
+
+//#region src/calc/normalizeCalc.d.ts
+/** Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded at 64), otherwise undefined. Never throws. */
+declare const normalizeCalc: (value: unknown) => CalcExpression | undefined;
+//#endregion
+export { normalizeCalc };
+//# sourceMappingURL=normalizeCalc.d.ts.map

package/dist/calc/normalizeCalc.js

@@ -0,0 +1,100 @@
+//#region src/calc/normalizeCalc.ts
+const MAX_DEPTH = 64;
+const OP_SET = new Set([
+	"+",
+	"-",
+	"*",
+	"/",
+	"%"
+]);
+const FN_SET = new Set([
+	"min",
+	"max",
+	"round",
+	"abs",
+	"ceil",
+	"floor"
+]);
+const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const normalizeNode = (value, depth) => {
+	if (depth > MAX_DEPTH) return void 0;
+	if (!isRecord(value)) return void 0;
+	switch (value.type) {
+		case "lit": {
+			const { value: v } = value;
+			if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
+			return {
+				type: "lit",
+				value: v
+			};
+		}
+		case "ref": {
+			const { field } = value;
+			if (typeof field !== "string") return void 0;
+			return {
+				type: "ref",
+				field
+			};
+		}
+		case "op": {
+			const { op, left, right } = value;
+			if (typeof op !== "string" || !OP_SET.has(op)) return void 0;
+			const l = normalizeNode(left, depth + 1);
+			if (!l) return void 0;
+			const r = normalizeNode(right, depth + 1);
+			if (!r) return void 0;
+			return {
+				type: "op",
+				op,
+				left: l,
+				right: r
+			};
+		}
+		case "neg": {
+			const operand = normalizeNode(value.operand, depth + 1);
+			if (!operand) return void 0;
+			return {
+				type: "neg",
+				operand
+			};
+		}
+		case "fn": {
+			const { fn, args } = value;
+			if (typeof fn !== "string" || !FN_SET.has(fn)) return void 0;
+			if (!Array.isArray(args)) return void 0;
+			const normalizedArgs = [];
+			for (const arg of args) {
+				const a = normalizeNode(arg, depth + 1);
+				if (!a) return void 0;
+				normalizedArgs.push(a);
+			}
+			return {
+				type: "fn",
+				fn,
+				args: normalizedArgs
+			};
+		}
+		case "weight": {
+			const { field, weights } = value;
+			if (typeof field !== "string") return void 0;
+			if (!isRecord(weights)) return void 0;
+			const normalizedWeights = {};
+			for (const [k, v] of Object.entries(weights)) {
+				if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
+				normalizedWeights[k] = v;
+			}
+			return {
+				type: "weight",
+				field,
+				weights: normalizedWeights
+			};
+		}
+		default: return;
+	}
+};
+/** Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded at 64), otherwise undefined. Never throws. */
+const normalizeCalc = (value) => normalizeNode(value, 0);
+//#endregion
+export { normalizeCalc };
+
+//# sourceMappingURL=normalizeCalc.js.map

package/dist/calc/normalizeCalc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeCalc.js","names":[],"sources":["../../src/calc/normalizeCalc.ts"],"sourcesContent":["import type { CalcExpression } from './types'\n\nconst MAX_DEPTH = 64\n\nconst OP_SET = new Set(['+', '-', '*', '/', '%'])\nconst FN_SET = new Set(['min', 'max', 'round', 'abs', 'ceil', 'floor'])\n\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n\tv !== null && typeof v === 'object' && !Array.isArray(v)\n\nconst normalizeNode = (value: unknown, depth: number): CalcExpression | undefined => {\n\tif (depth > MAX_DEPTH) return undefined\n\tif (!isRecord(value)) return undefined\n\n\tswitch (value.type) {\n\t\tcase 'lit': {\n\t\t\tconst { value: v } = value\n\t\t\tif (typeof v !== 'number' || !Number.isFinite(v)) return undefined\n\t\t\treturn { type: 'lit', value: v }\n\t\t}\n\t\tcase 'ref': {\n\t\t\tconst { field } = value\n\t\t\tif (typeof field !== 'string') return undefined\n\t\t\treturn { type: 'ref', field }\n\t\t}\n\t\tcase 'op': {\n\t\t\tconst { op, left, right } = value\n\t\t\tif (typeof op !== 'string' || !OP_SET.has(op)) return undefined\n\t\t\tconst l = normalizeNode(left, depth + 1)\n\t\t\tif (!l) return undefined\n\t\t\tconst r = normalizeNode(right, depth + 1)\n\t\t\tif (!r) return undefined\n\t\t\treturn { type: 'op', op: op as '+' | '-' | '*' | '/' | '%', left: l, right: r }\n\t\t}\n\t\tcase 'neg': {\n\t\t\tconst operand = normalizeNode(value.operand, depth + 1)\n\t\t\tif (!operand) return undefined\n\t\t\treturn { type: 'neg', operand }\n\t\t}\n\t\tcase 'fn': {\n\t\t\tconst { fn, args } = value\n\t\t\tif (typeof fn !== 'string' || !FN_SET.has(fn)) return undefined\n\t\t\tif (!Array.isArray(args)) return undefined\n\t\t\tconst normalizedArgs: CalcExpression[] = []\n\t\t\tfor (const arg of args) {\n\t\t\t\tconst a = normalizeNode(arg, depth + 1)\n\t\t\t\tif (!a) return undefined\n\t\t\t\tnormalizedArgs.push(a)\n\t\t\t}\n\t\t\treturn {\n\t\t\t\ttype: 'fn',\n\t\t\t\tfn: fn as 'min' | 'max' | 'round' | 'abs' | 'ceil' | 'floor',\n\t\t\t\targs: normalizedArgs,\n\t\t\t}\n\t\t}\n\t\tcase 'weight': {\n\t\t\tconst { field, weights } = value\n\t\t\tif (typeof field !== 'string') return undefined\n\t\t\tif (!isRecord(weights)) return undefined\n\t\t\tconst normalizedWeights: Record<string, number> = {}\n\t\t\tfor (const [k, v] of Object.entries(weights)) {\n\t\t\t\tif (typeof v !== 'number' || !Number.isFinite(v)) return undefined\n\t\t\t\tnormalizedWeights[k] = v\n\t\t\t}\n\t\t\treturn { type: 'weight', field, weights: normalizedWeights }\n\t\t}\n\t\tdefault:\n\t\t\treturn undefined\n\t}\n}\n\n/** Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded at 64), otherwise undefined. Never throws. */\nexport const normalizeCalc = (value: unknown): CalcExpression | undefined => normalizeNode(value, 0)\n"],"mappings":";AAEA,MAAM,YAAY;AAElB,MAAM,SAAS,IAAI,IAAI;CAAC;CAAK;CAAK;CAAK;CAAK;AAAG,CAAC;AAChD,MAAM,SAAS,IAAI,IAAI;CAAC;CAAO;CAAO;CAAS;CAAO;CAAQ;AAAO,CAAC;AAEtE,MAAM,YAAY,MACjB,MAAM,QAAQ,OAAO,MAAM,YAAY,CAAC,MAAM,QAAQ,CAAC;AAExD,MAAM,iBAAiB,OAAgB,UAA8C;CACpF,IAAI,QAAQ,WAAW,OAAO,KAAA;CAC9B,IAAI,CAAC,SAAS,KAAK,GAAG,OAAO,KAAA;CAE7B,QAAQ,MAAM,MAAd;EACC,KAAK,OAAO;GACX,MAAM,EAAE,OAAO,MAAM;GACrB,IAAI,OAAO,MAAM,YAAY,CAAC,OAAO,SAAS,CAAC,GAAG,OAAO,KAAA;GACzD,OAAO;IAAE,MAAM;IAAO,OAAO;GAAE;EAChC;EACA,KAAK,OAAO;GACX,MAAM,EAAE,UAAU;GAClB,IAAI,OAAO,UAAU,UAAU,OAAO,KAAA;GACtC,OAAO;IAAE,MAAM;IAAO;GAAM;EAC7B;EACA,KAAK,MAAM;GACV,MAAM,EAAE,IAAI,MAAM,UAAU;GAC5B,IAAI,OAAO,OAAO,YAAY,CAAC,OAAO,IAAI,EAAE,GAAG,OAAO,KAAA;GACtD,MAAM,IAAI,cAAc,MAAM,QAAQ,CAAC;GACvC,IAAI,CAAC,GAAG,OAAO,KAAA;GACf,MAAM,IAAI,cAAc,OAAO,QAAQ,CAAC;GACxC,IAAI,CAAC,GAAG,OAAO,KAAA;GACf,OAAO;IAAE,MAAM;IAAU;IAAmC,MAAM;IAAG,OAAO;GAAE;EAC/E;EACA,KAAK,OAAO;GACX,MAAM,UAAU,cAAc,MAAM,SAAS,QAAQ,CAAC;GACtD,IAAI,CAAC,SAAS,OAAO,KAAA;GACrB,OAAO;IAAE,MAAM;IAAO;GAAQ;EAC/B;EACA,KAAK,MAAM;GACV,MAAM,EAAE,IAAI,SAAS;GACrB,IAAI,OAAO,OAAO,YAAY,CAAC,OAAO,IAAI,EAAE,GAAG,OAAO,KAAA;GACtD,IAAI,CAAC,MAAM,QAAQ,IAAI,GAAG,OAAO,KAAA;GACjC,MAAM,iBAAmC,CAAC;GAC1C,KAAK,MAAM,OAAO,MAAM;IACvB,MAAM,IAAI,cAAc,KAAK,QAAQ,CAAC;IACtC,IAAI,CAAC,GAAG,OAAO,KAAA;IACf,eAAe,KAAK,CAAC;GACtB;GACA,OAAO;IACN,MAAM;IACF;IACJ,MAAM;GACP;EACD;EACA,KAAK,UAAU;GACd,MAAM,EAAE,OAAO,YAAY;GAC3B,IAAI,OAAO,UAAU,UAAU,OAAO,KAAA;GACtC,IAAI,CAAC,SAAS,OAAO,GAAG,OAAO,KAAA;GAC/B,MAAM,oBAA4C,CAAC;GACnD,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,OAAO,GAAG;IAC7C,IAAI,OAAO,MAAM,YAAY,CAAC,OAAO,SAAS,CAAC,GAAG,OAAO,KAAA;IACzD,kBAAkB,KAAK;GACxB;GACA,OAAO;IAAE,MAAM;IAAU;IAAO,SAAS;GAAkB;EAC5D;EACA,SACC;CACF;AACD;;AAGA,MAAa,iBAAiB,UAA+C,cAAc,OAAO,CAAC"}

package/dist/calc/types.d.ts

@@ -0,0 +1,28 @@
+//#region src/calc/types.d.ts
+/** A serializable, safe-by-construction calculation expression. No strings are parsed; the evaluator tree-walks this closed node set (never `eval`). */
+type CalcExpression = {
+  type: 'lit';
+  value: number;
+} | {
+  type: 'ref';
+  field: string;
+} | {
+  type: 'op';
+  op: '+' | '-' | '*' | '/' | '%';
+  left: CalcExpression;
+  right: CalcExpression;
+} | {
+  type: 'neg';
+  operand: CalcExpression;
+} | {
+  type: 'fn';
+  fn: 'min' | 'max' | 'round' | 'abs' | 'ceil' | 'floor';
+  args: CalcExpression[];
+} | {
+  type: 'weight';
+  field: string;
+  weights: Record<string, number>;
+};
+//#endregion
+export { CalcExpression };
+//# sourceMappingURL=types.d.ts.map