@everysk/apps-sdk 0.2.0 → 0.3.0-beta-20261016180126

package/dist/lib/datastoreTable.d.ts

@@ -1,4 +1,5 @@
-import type { Datastore } from "../types/datastore.d.ts";
+import type { Datastore, ParsedDatastore } from "../types/datastore.d.ts";
+import type { DatastoreDataFormat } from "../types/datastoreDataFormat.d.ts";
 import type { AnyRecord } from "../types/anyRecord.d.ts";
 type Cell = string | number | null;
 type DatastoreData = Cell[][];
@@ -32,13 +33,49 @@ type DatastoreData = Cell[][];
  *   ["Alice", 30],
  *   ["Bob", null],
  * ];
- * const rows = tableToObjects("ds_123", headers, data);
+ * const rows = matrixToObjects("ds_123", headers, data);
  * // [
  * //   { datastoreId: "ds_123", name: "Alice", age: 30 },
  * //   { datastoreId: "ds_123", name: "Bob", age: null }
  * // ]
  */
-export declare const tableToObjects: <T extends Record<string, Cell>>(datastoreId: string, headers: string[], data: DatastoreData) => T[];
+export declare const matrixToObjects: <T extends Record<string, Cell>>(datastoreId: string, headers: string[], data: DatastoreData) => T[];
+/**
+ * Converts a datastore as the API returns it into the shape the datastore hooks return.
+ *
+ * A datastore is tabular or JSON, and the API does not say which. `data` is a matrix, an object,
+ * or an array of objects, so only an array whose every element is an array is read as a table.
+ * "Any array" is not enough: the API has returned `[{ … }]` for a JSON datastore, which read as a
+ * matrix lost its content with one element and threw with two. A table's matrix becomes row
+ * objects, with the header row kept as `fields` so that saving back can restore the column
+ * order. JSON passes through untouched.
+ *
+ * A read without its data (`projection: "-data"`) carries nothing to tell the kinds apart and
+ * comes back as an empty table.
+ *
+ * The hooks convert in the request rather than in `select`, so the cache holds objects and an
+ * app patches a row as `{ ...row, ...patch }` rather than by column index. It is exported for an
+ * app that seeds that cache itself.
+ *
+ * With `dataFormat: "matrix"` a table keeps its matrix unconverted, header row included, and still
+ * gets `fields`. JSON is untouched either way.
+ *
+ * @param datastore The datastore as the API returned it.
+ * @param dataFormat `"object"` (default) or `"matrix"`.
+ * @returns A tabular or a `JsonDatastore`, told apart by `format`.
+ */
+export declare function parseDatastore(datastore: Datastore): ParsedDatastore;
+export declare function parseDatastore<F extends DatastoreDataFormat>(datastore: Datastore, dataFormat: F): ParsedDatastore<F>;
+/**
+ * Narrows a datastore to a tabular one, whose `data` is rows. For a `select` over a list that
+ * may mix kinds: `datastores.filter(isTableDatastore).flatMap((d) => d.data)`.
+ *
+ * @param datastore A datastore as the hooks return it.
+ * @returns True for a tabular datastore.
+ */
+export declare const isTableDatastore: <D extends ParsedDatastore<DatastoreDataFormat>>(datastore: D) => datastore is Extract<D, {
+    format: "table";
+}>;
 /**
  * Converts an array of objects into a datastore table (2D array).
  *
@@ -47,7 +84,8 @@ export declare const tableToObjects: <T extends Record<string, Cell>>(datastoreI
  * - For each object in `data`, creates a row by mapping `headers` to values in the object.
  * - If a header is missing in an object, the corresponding cell is set to `null`.
  *
- * @template T A record type whose values are compatible with `Cell` (string | number | null).
+ * Takes rows as the datastore hooks hand them over (`AnyRecord`): a value that is not a cell is
+ * written as it is, since the row came from a matrix in the first place.
  *
  * @param headers Column names (and output table header row).
  * @param data Array of objects to convert into rows.
@@ -58,7 +96,7 @@ export declare const tableToObjects: <T extends Record<string, Cell>>(datastoreI
  *
  * @example
  * const headers = ["name", "age"];
- * const rows = objectsToTable(headers, [
+ * const rows = objectsToMatrix(headers, [
  *   { name: "Alice", age: 30 },
  *   { name: "Bob" }, // age missing -> null
  * ]);
@@ -68,59 +106,26 @@ export declare const tableToObjects: <T extends Record<string, Cell>>(datastoreI
  * //   ["Bob", null]
  * // ]
  */
-export declare const objectsToTable: <T extends Record<string, Cell>>(headers: string[], data: T[]) => DatastoreData;
+export declare const objectsToMatrix: <T extends AnyRecord = AnyRecord>(headers: string[], data: T[]) => DatastoreData;
 /**
- * Flattens multiple datastore row arrays into a single array.
+ * The matrix of a tabular datastore, however the hook read it. Code that saves or exports a
+ * datastore calls this without knowing the `dataFormat` it was read with: a matrix read is
+ * copied, an object read is rebuilt in the datastore's own column order (`fields`), without the
+ * `datastoreId` the SDK adds to each row, and with any patch applied to the rows.
  *
- * This is typically used after fetching multiple datastores, where each datastore is
- * represented as `AnyRecord[]` (i.e., an array of row objects).
+ * Either way the result is a new matrix the caller owns and may edit before saving. A matrix
+ * read's `data` is the matrix in the query cache, and handing that back made an edit change what
+ * every screen reading the entry sees.
  *
- * @param datastores A list of datastores, each represented as an array of row objects.
+ * Do not save the result of a read that projected `data` away (`projection: "-data"`): it comes
+ * back as an empty table, indistinguishable from a real one, and saving it would empty the
+ * datastore.
  *
- * @returns A single array containing all rows from all datastores, in the same order.
- *
- * @example
- * const merged = mergeDatastores([
- *   [{ datastoreId: "a", x: 1 }],
- *   [{ datastoreId: "b", x: 2 }, { datastoreId: "b", x: 3 }],
- * ]);
- * // [{...}, {...}, {...}]
- */
-export declare const mergeDatastores: (datastores: AnyRecord[][]) => AnyRecord[];
-/**
- * buildDatastoreProps
- *
- * Extracts and maps the metadata properties of a `Datastore` into a plain object
- * for UI usage, discarding raw data rows.
- *
- * - `header` is derived from `datastore.data?.[0]` (the first row of the data matrix),
- *   which is expected to contain the column names. Falls back to `[]` if not present.
- *
- * @param {Datastore} datastore - The source datastore object.
- * @returns Metadata object with the datastore's descriptive properties and header.
- *
- * @example
- * const meta = buildDatastoreProps(datastore);
- * // {
- * //   name: "my-datastore",
- * //   workspace: "ws-1",
- * //   header: ["col1", "col2"],
- * //   ...
- * // }
+ * @param datastore A tabular datastore as the hooks return it (narrow with `isTableDatastore`).
+ * @returns The matrix, header row first.
  */
-export declare const buildDatastoreProps: (datastore: Datastore) => {
-    name: string;
-    date: string | undefined;
-    version: string | undefined;
-    description: string | undefined;
-    tags: string[] | undefined;
-    link_uid: string | undefined;
-    workspace: string;
-    date_time: string;
-    created: number | undefined;
-    updated: number | undefined;
-    level: string | undefined;
-    header: import("../types/datastore.d.ts").DatastoreRow[];
-};
+export declare const toDatastoreMatrix: (datastore: Extract<ParsedDatastore<DatastoreDataFormat>, {
+    format: "table";
+}>) => DatastoreData;
 export {};
 //# sourceMappingURL=datastoreTable.d.ts.map

package/dist/lib/datastoreTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"datastoreTable.d.ts","sourceRoot":"","sources":["../../src/lib/datastoreTable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,KAAK,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AACnC,KAAK,aAAa,GAAG,IAAI,EAAE,EAAE,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,aAAa,KAAG,CAAC,EAgB7H,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,KAAG,aAI7F,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAAI,YAAY,SAAS,EAAE,EAAE,KAAG,SAAS,EAQpE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,GAAI,WAAW,SAAS;;;;;;;;;;;;;CAevD,CAAC"}
+{"version":3,"file":"datastoreTable.d.ts","sourceRoot":"","sources":["../../src/lib/datastoreTable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAiB,MAAM,mBAAmB,CAAC;AACnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,KAAK,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AACnC,KAAK,aAAa,GAAG,IAAI,EAAE,EAAE,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAC1D,aAAa,MAAM,EACnB,SAAS,MAAM,EAAE,EACjB,MAAM,aAAa,KACpB,CAAC,EAgBH,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,CAAC;AACtE,wBAAgB,cAAc,CAAC,CAAC,SAAS,mBAAmB,EACxD,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,CAAC,GACd,eAAe,CAAC,CAAC,CAAC,CAAC;AA0BtB;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,eAAe,CAAC,mBAAmB,CAAC,EAC3E,WAAW,CAAC,KACb,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAiC,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EAC3D,SAAS,MAAM,EAAE,EACjB,MAAM,CAAC,EAAE,KACV,aAUF,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,GAC1B,WAAW,OAAO,CAAC,eAAe,CAAC,mBAAmB,CAAC,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,KAC9E,aAaF,CAAC"}

package/dist/lib/datastoreTable.js

@@ -29,13 +29,13 @@
 *   ["Alice", 30],
 *   ["Bob", null],
 * ];
-* const rows = tableToObjects("ds_123", headers, data);
+* const rows = matrixToObjects("ds_123", headers, data);
 * // [
 * //   { datastoreId: "ds_123", name: "Alice", age: 30 },
 * //   { datastoreId: "ds_123", name: "Bob", age: null }
 * // ]
 */
-var tableToObjects = (datastoreId, headers, data) => {
+var matrixToObjects = (datastoreId, headers, data) => {
 	const result = [];
 	for (let i = 1; i < data?.length; i++) {
 		const item = {};
@@ -47,6 +47,38 @@ var tableToObjects = (datastoreId, headers, data) => {
 	}
 	return result;
 };
+/** A tabular datastore's `data`: an array of rows. An empty array counts, as an empty table. */
+var isMatrix = (data) => Array.isArray(data) && data.every(Array.isArray);
+function parseDatastore(datastore, dataFormat = "object") {
+	const { data } = datastore;
+	if (data && !isMatrix(data)) return {
+		...datastore,
+		format: "json",
+		data
+	};
+	const matrix = data ?? [];
+	const fields = matrix[0] ?? [];
+	if (dataFormat === "matrix") return {
+		...datastore,
+		format: "table",
+		fields,
+		data: matrix
+	};
+	return {
+		...datastore,
+		format: "table",
+		fields,
+		data: matrixToObjects(datastore.id, fields, matrix)
+	};
+}
+/**
+* Narrows a datastore to a tabular one, whose `data` is rows. For a `select` over a list that
+* may mix kinds: `datastores.filter(isTableDatastore).flatMap((d) => d.data)`.
+*
+* @param datastore A datastore as the hooks return it.
+* @returns True for a tabular datastore.
+*/
+var isTableDatastore = (datastore) => datastore.format === "table";
 /**
 * Converts an array of objects into a datastore table (2D array).
 *
@@ -55,7 +87,8 @@ var tableToObjects = (datastoreId, headers, data) => {
 * - For each object in `data`, creates a row by mapping `headers` to values in the object.
 * - If a header is missing in an object, the corresponding cell is set to `null`.
 *
-* @template T A record type whose values are compatible with `Cell` (string | number | null).
+* Takes rows as the datastore hooks hand them over (`AnyRecord`): a value that is not a cell is
+* written as it is, since the row came from a matrix in the first place.
 *
 * @param headers Column names (and output table header row).
 * @param data Array of objects to convert into rows.
@@ -66,7 +99,7 @@ var tableToObjects = (datastoreId, headers, data) => {
 *
 * @example
 * const headers = ["name", "age"];
-* const rows = objectsToTable(headers, [
+* const rows = objectsToMatrix(headers, [
 *   { name: "Alice", age: 30 },
 *   { name: "Bob" }, // age missing -> null
 * ]);
@@ -76,71 +109,34 @@ var tableToObjects = (datastoreId, headers, data) => {
 * //   ["Bob", null]
 * // ]
 */
-var objectsToTable = (headers, data) => {
-	return [headers, ...data.map((d) => headers.map((h) => d[h] ?? null))];
+var objectsToMatrix = (headers, data) => {
+	const matrix = [headers.slice()];
+	for (const row of data) matrix.push(headers.map((header) => row[header] ?? null));
+	return matrix;
 };
 /**
-* Flattens multiple datastore row arrays into a single array.
-*
-* This is typically used after fetching multiple datastores, where each datastore is
-* represented as `AnyRecord[]` (i.e., an array of row objects).
+* The matrix of a tabular datastore, however the hook read it. Code that saves or exports a
+* datastore calls this without knowing the `dataFormat` it was read with: a matrix read is
+* copied, an object read is rebuilt in the datastore's own column order (`fields`), without the
+* `datastoreId` the SDK adds to each row, and with any patch applied to the rows.
 *
-* @param datastores A list of datastores, each represented as an array of row objects.
+* Either way the result is a new matrix the caller owns and may edit before saving. A matrix
+* read's `data` is the matrix in the query cache, and handing that back made an edit change what
+* every screen reading the entry sees.
 *
-* @returns A single array containing all rows from all datastores, in the same order.
+* Do not save the result of a read that projected `data` away (`projection: "-data"`): it comes
+* back as an empty table, indistinguishable from a real one, and saving it would empty the
+* datastore.
 *
-* @example
-* const merged = mergeDatastores([
-*   [{ datastoreId: "a", x: 1 }],
-*   [{ datastoreId: "b", x: 2 }, { datastoreId: "b", x: 3 }],
-* ]);
-* // [{...}, {...}, {...}]
+* @param datastore A tabular datastore as the hooks return it (narrow with `isTableDatastore`).
+* @returns The matrix, header row first.
 */
-var mergeDatastores = (datastores) => {
-	const result = [];
-	datastores.forEach((datastore) => {
-		result.push(...datastore);
-	});
-	return result;
-};
-/**
-* buildDatastoreProps
-*
-* Extracts and maps the metadata properties of a `Datastore` into a plain object
-* for UI usage, discarding raw data rows.
-*
-* - `header` is derived from `datastore.data?.[0]` (the first row of the data matrix),
-*   which is expected to contain the column names. Falls back to `[]` if not present.
-*
-* @param {Datastore} datastore - The source datastore object.
-* @returns Metadata object with the datastore's descriptive properties and header.
-*
-* @example
-* const meta = buildDatastoreProps(datastore);
-* // {
-* //   name: "my-datastore",
-* //   workspace: "ws-1",
-* //   header: ["col1", "col2"],
-* //   ...
-* // }
-*/
-var buildDatastoreProps = (datastore) => {
-	return {
-		name: datastore.name,
-		date: datastore.date,
-		version: datastore.version,
-		description: datastore.description,
-		tags: datastore.tags,
-		link_uid: datastore.link_uid,
-		workspace: datastore.workspace,
-		date_time: datastore.date_time,
-		created: datastore.created,
-		updated: datastore.updated,
-		level: datastore.level,
-		header: datastore.data?.[0] || []
-	};
+var toDatastoreMatrix = (datastore) => {
+	const { data, fields } = datastore;
+	if (data.length === 0) return fields.length > 0 ? [fields.slice()] : [];
+	return Array.isArray(data[0]) ? data.map((row) => row.slice()) : objectsToMatrix(fields, data);
 };
 //#endregion
-export { buildDatastoreProps, mergeDatastores, objectsToTable, tableToObjects };
+export { isTableDatastore, matrixToObjects, objectsToMatrix, parseDatastore, toDatastoreMatrix };
 
 //# sourceMappingURL=datastoreTable.js.map

package/dist/lib/datastoreTable.js.map

@@ -1 +1 @@
-{"version":3,"file":"datastoreTable.js","names":[],"sources":["../../src/lib/datastoreTable.ts"],"sourcesContent":["import type { Datastore } from \"@/types/datastore\";\nimport type { AnyRecord } from \"@/types/anyRecord\";\n\ntype Cell = string | number | null;\ntype DatastoreData = Cell[][];\n\n/**\n * Converts a datastore table (2D array) into an array of objects.\n *\n * The input `data` is expected to be a 2D array where:\n * - Row 0 typically contains the headers (but headers are provided explicitly via `headers`)\n * - Rows 1..N contain the data values\n *\n * Key behaviors:\n * - Skips the first row of `data` (starts at index 1), assuming it is the header row.\n * - Adds a `datastoreId` field to every generated object so each record can be traced\n *   back to its source datastore.\n * - Maps each header to the corresponding cell value by column index.\n *\n * @template T A record type whose values are compatible with `Cell` (string | number | null).\n *\n * @param datastoreId The id of the datastore to attach to each row as `datastoreId`.\n * @param headers The column names used as object keys (positionally aligned with row cells).\n * @param data The datastore matrix (rows x columns). Row 0 is assumed to be headers.\n *\n * @returns An array of objects (one per data row), each containing:\n * - `datastoreId`\n * - one property per header (with the corresponding cell value)\n *\n * @example\n * const headers = [\"name\", \"age\"];\n * const data = [\n *   [\"name\", \"age\"],\n *   [\"Alice\", 30],\n *   [\"Bob\", null],\n * ];\n * const rows = tableToObjects(\"ds_123\", headers, data);\n * // [\n * //   { datastoreId: \"ds_123\", name: \"Alice\", age: 30 },\n * //   { datastoreId: \"ds_123\", name: \"Bob\", age: null }\n * // ]\n */\nexport const tableToObjects = <T extends Record<string, Cell>>(datastoreId: string, headers: string[], data: DatastoreData): T[] => {\n  const result: T[] = [];\n\n  for (let i = 1; i < data?.length; i++) {\n    const item: Record<string, Cell> = {};\n\n    item.datastoreId = datastoreId;\n\n    headers.forEach((header: string, index: number) => {\n      item[header] = data[i][index];\n    });\n\n    result.push(item as T);\n  }\n\n  return result;\n};\n\n/**\n * Converts an array of objects into a datastore table (2D array).\n *\n * Key behaviors:\n * - Produces a 2D array where the first row is the provided `headers`.\n * - For each object in `data`, creates a row by mapping `headers` to values in the object.\n * - If a header is missing in an object, the corresponding cell is set to `null`.\n *\n * @template T A record type whose values are compatible with `Cell` (string | number | null).\n *\n * @param headers Column names (and output table header row).\n * @param data Array of objects to convert into rows.\n *\n * @returns A datastore matrix where:\n * - Row 0 is `headers`\n * - Rows 1..N contain cell values aligned with `headers`\n *\n * @example\n * const headers = [\"name\", \"age\"];\n * const rows = objectsToTable(headers, [\n *   { name: \"Alice\", age: 30 },\n *   { name: \"Bob\" }, // age missing -> null\n * ]);\n * // [\n * //   [\"name\", \"age\"],\n * //   [\"Alice\", 30],\n * //   [\"Bob\", null]\n * // ]\n */\nexport const objectsToTable = <T extends Record<string, Cell>>(headers: string[] ,data: T[]): DatastoreData => {\n  const rows: DatastoreData = data.map((d) => headers.map<Cell>((h) => d[h as string] ?? null));\n\n  return [headers, ...rows];\n};\n\n/**\n * Flattens multiple datastore row arrays into a single array.\n *\n * This is typically used after fetching multiple datastores, where each datastore is\n * represented as `AnyRecord[]` (i.e., an array of row objects).\n *\n * @param datastores A list of datastores, each represented as an array of row objects.\n *\n * @returns A single array containing all rows from all datastores, in the same order.\n *\n * @example\n * const merged = mergeDatastores([\n *   [{ datastoreId: \"a\", x: 1 }],\n *   [{ datastoreId: \"b\", x: 2 }, { datastoreId: \"b\", x: 3 }],\n * ]);\n * // [{...}, {...}, {...}]\n */\nexport const mergeDatastores = (datastores: AnyRecord[][]): AnyRecord[] => {\n  const result: AnyRecord[] = [];\n\n  datastores.forEach((datastore: AnyRecord[]) => {\n    result.push(...datastore);\n  });\n\n  return result;\n};\n\n/**\n * buildDatastoreProps\n *\n * Extracts and maps the metadata properties of a `Datastore` into a plain object\n * for UI usage, discarding raw data rows.\n *\n * - `header` is derived from `datastore.data?.[0]` (the first row of the data matrix),\n *   which is expected to contain the column names. Falls back to `[]` if not present.\n *\n * @param {Datastore} datastore - The source datastore object.\n * @returns Metadata object with the datastore's descriptive properties and header.\n *\n * @example\n * const meta = buildDatastoreProps(datastore);\n * // {\n * //   name: \"my-datastore\",\n * //   workspace: \"ws-1\",\n * //   header: [\"col1\", \"col2\"],\n * //   ...\n * // }\n */\nexport const buildDatastoreProps = (datastore: Datastore) => {\n    return {\n        name: datastore.name,\n        date: datastore.date,\n        version: datastore.version,\n        description: datastore.description,\n        tags: datastore.tags,\n        link_uid: datastore.link_uid,\n        workspace: datastore.workspace,\n        date_time: datastore.date_time,\n        created: datastore.created,\n        updated: datastore.updated,\n        level: datastore.level,\n        header: datastore.data?.[0] || [],\n    };\n};"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,IAAa,kBAAkD,aAAqB,SAAmB,SAA6B;CAClI,MAAM,SAAc,CAAC;CAErB,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,OAA6B,CAAC;EAEpC,KAAK,cAAc;EAEnB,QAAQ,SAAS,QAAgB,UAAkB;GACjD,KAAK,UAAU,KAAK,EAAE,CAAC;EACzB,CAAC;EAED,OAAO,KAAK,IAAS;CACvB;CAEA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,IAAa,kBAAkD,SAAmB,SAA6B;CAG7G,OAAO,CAAC,SAAS,GAFW,KAAK,KAAK,MAAM,QAAQ,KAAW,MAAM,EAAE,MAAgB,IAAI,CAEvE,CAAI;AAC1B;;;;;;;;;;;;;;;;;;AAmBA,IAAa,mBAAmB,eAA2C;CACzE,MAAM,SAAsB,CAAC;CAE7B,WAAW,SAAS,cAA2B;EAC7C,OAAO,KAAK,GAAG,SAAS;CAC1B,CAAC;CAED,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,uBAAuB,cAAyB;CACzD,OAAO;EACH,MAAM,UAAU;EAChB,MAAM,UAAU;EAChB,SAAS,UAAU;EACnB,aAAa,UAAU;EACvB,MAAM,UAAU;EAChB,UAAU,UAAU;EACpB,WAAW,UAAU;EACrB,WAAW,UAAU;EACrB,SAAS,UAAU;EACnB,SAAS,UAAU;EACnB,OAAO,UAAU;EACjB,QAAQ,UAAU,OAAO,MAAM,CAAC;CACpC;AACJ"}
+{"version":3,"file":"datastoreTable.js","names":[],"sources":["../../src/lib/datastoreTable.ts"],"sourcesContent":["import type { Datastore, ParsedDatastore, JsonDatastore } from \"@/types/datastore\";\nimport type { DatastoreDataFormat } from \"@/types/datastoreDataFormat\";\nimport type { AnyRecord } from \"@/types/anyRecord\";\n\ntype Cell = string | number | null;\ntype DatastoreData = Cell[][];\n\n/**\n * Converts a datastore table (2D array) into an array of objects.\n *\n * The input `data` is expected to be a 2D array where:\n * - Row 0 typically contains the headers (but headers are provided explicitly via `headers`)\n * - Rows 1..N contain the data values\n *\n * Key behaviors:\n * - Skips the first row of `data` (starts at index 1), assuming it is the header row.\n * - Adds a `datastoreId` field to every generated object so each record can be traced\n *   back to its source datastore.\n * - Maps each header to the corresponding cell value by column index.\n *\n * @template T A record type whose values are compatible with `Cell` (string | number | null).\n *\n * @param datastoreId The id of the datastore to attach to each row as `datastoreId`.\n * @param headers The column names used as object keys (positionally aligned with row cells).\n * @param data The datastore matrix (rows x columns). Row 0 is assumed to be headers.\n *\n * @returns An array of objects (one per data row), each containing:\n * - `datastoreId`\n * - one property per header (with the corresponding cell value)\n *\n * @example\n * const headers = [\"name\", \"age\"];\n * const data = [\n *   [\"name\", \"age\"],\n *   [\"Alice\", 30],\n *   [\"Bob\", null],\n * ];\n * const rows = matrixToObjects(\"ds_123\", headers, data);\n * // [\n * //   { datastoreId: \"ds_123\", name: \"Alice\", age: 30 },\n * //   { datastoreId: \"ds_123\", name: \"Bob\", age: null }\n * // ]\n */\nexport const matrixToObjects = <T extends Record<string, Cell>>(\n    datastoreId: string,\n    headers: string[],\n    data: DatastoreData,\n): T[] => {\n    const result: T[] = [];\n\n    for (let i = 1; i < data?.length; i++) {\n        const item: Record<string, Cell> = {};\n\n        item.datastoreId = datastoreId;\n\n        headers.forEach((header: string, index: number) => {\n            item[header] = data[i][index];\n        });\n\n        result.push(item as T);\n    }\n\n    return result;\n};\n\n/** A tabular datastore's `data`: an array of rows. An empty array counts, as an empty table. */\nconst isMatrix = (data: unknown): data is DatastoreData =>\n    Array.isArray(data) && data.every(Array.isArray);\n\n/**\n * Converts a datastore as the API returns it into the shape the datastore hooks return.\n *\n * A datastore is tabular or JSON, and the API does not say which. `data` is a matrix, an object,\n * or an array of objects, so only an array whose every element is an array is read as a table.\n * \"Any array\" is not enough: the API has returned `[{ … }]` for a JSON datastore, which read as a\n * matrix lost its content with one element and threw with two. A table's matrix becomes row\n * objects, with the header row kept as `fields` so that saving back can restore the column\n * order. JSON passes through untouched.\n *\n * A read without its data (`projection: \"-data\"`) carries nothing to tell the kinds apart and\n * comes back as an empty table.\n *\n * The hooks convert in the request rather than in `select`, so the cache holds objects and an\n * app patches a row as `{ ...row, ...patch }` rather than by column index. It is exported for an\n * app that seeds that cache itself.\n *\n * With `dataFormat: \"matrix\"` a table keeps its matrix unconverted, header row included, and still\n * gets `fields`. JSON is untouched either way.\n *\n * @param datastore The datastore as the API returned it.\n * @param dataFormat `\"object\"` (default) or `\"matrix\"`.\n * @returns A tabular or a `JsonDatastore`, told apart by `format`.\n */\nexport function parseDatastore(datastore: Datastore): ParsedDatastore;\nexport function parseDatastore<F extends DatastoreDataFormat>(\n    datastore: Datastore,\n    dataFormat: F,\n): ParsedDatastore<F>;\nexport function parseDatastore(\n    datastore: Datastore,\n    dataFormat: DatastoreDataFormat = \"object\",\n): ParsedDatastore<DatastoreDataFormat> {\n    const { data } = datastore;\n\n    if (data && !isMatrix(data)) {\n        return { ...datastore, format: \"json\", data: data as JsonDatastore[\"data\"] };\n    }\n\n    const matrix = (data ?? []) as DatastoreData;\n    const fields = (matrix[0] ?? []) as string[];\n\n    if (dataFormat === \"matrix\") {\n        return { ...datastore, format: \"table\", fields, data: matrix };\n    }\n\n    return {\n        ...datastore,\n        format: \"table\",\n        fields,\n        data: matrixToObjects(datastore.id, fields, matrix),\n    };\n}\n\n/**\n * Narrows a datastore to a tabular one, whose `data` is rows. For a `select` over a list that\n * may mix kinds: `datastores.filter(isTableDatastore).flatMap((d) => d.data)`.\n *\n * @param datastore A datastore as the hooks return it.\n * @returns True for a tabular datastore.\n */\nexport const isTableDatastore = <D extends ParsedDatastore<DatastoreDataFormat>>(\n    datastore: D,\n): datastore is Extract<D, { format: \"table\" }> => datastore.format === \"table\";\n\n/**\n * Converts an array of objects into a datastore table (2D array).\n *\n * Key behaviors:\n * - Produces a 2D array where the first row is the provided `headers`.\n * - For each object in `data`, creates a row by mapping `headers` to values in the object.\n * - If a header is missing in an object, the corresponding cell is set to `null`.\n *\n * Takes rows as the datastore hooks hand them over (`AnyRecord`): a value that is not a cell is\n * written as it is, since the row came from a matrix in the first place.\n *\n * @param headers Column names (and output table header row).\n * @param data Array of objects to convert into rows.\n *\n * @returns A datastore matrix where:\n * - Row 0 is `headers`\n * - Rows 1..N contain cell values aligned with `headers`\n *\n * @example\n * const headers = [\"name\", \"age\"];\n * const rows = objectsToMatrix(headers, [\n *   { name: \"Alice\", age: 30 },\n *   { name: \"Bob\" }, // age missing -> null\n * ]);\n * // [\n * //   [\"name\", \"age\"],\n * //   [\"Alice\", 30],\n * //   [\"Bob\", null]\n * // ]\n */\nexport const objectsToMatrix = <T extends AnyRecord = AnyRecord>(\n    headers: string[],\n    data: T[],\n): DatastoreData => {\n    // Built into one array: mapping the rows and then spreading them after the header copied the\n    // whole list a second time. The header is copied: a caller's `headers` is often a datastore's\n    // `fields`, held in the query cache, and renaming a column in the matrix renamed it there too.\n    const matrix: DatastoreData = [headers.slice()];\n\n    for (const row of data)\n        matrix.push(headers.map<Cell>((header) => (row[header] ?? null) as Cell));\n\n    return matrix;\n};\n\n/**\n * The matrix of a tabular datastore, however the hook read it. Code that saves or exports a\n * datastore calls this without knowing the `dataFormat` it was read with: a matrix read is\n * copied, an object read is rebuilt in the datastore's own column order (`fields`), without the\n * `datastoreId` the SDK adds to each row, and with any patch applied to the rows.\n *\n * Either way the result is a new matrix the caller owns and may edit before saving. A matrix\n * read's `data` is the matrix in the query cache, and handing that back made an edit change what\n * every screen reading the entry sees.\n *\n * Do not save the result of a read that projected `data` away (`projection: \"-data\"`): it comes\n * back as an empty table, indistinguishable from a real one, and saving it would empty the\n * datastore.\n *\n * @param datastore A tabular datastore as the hooks return it (narrow with `isTableDatastore`).\n * @returns The matrix, header row first.\n */\nexport const toDatastoreMatrix = (\n    datastore: Extract<ParsedDatastore<DatastoreDataFormat>, { format: \"table\" }>,\n): DatastoreData => {\n    const { data, fields } = datastore;\n\n    if (data.length === 0) return fields.length > 0 ? [fields.slice()] : [];\n\n    // The first row is enough: the SDK built this `data`, so it is all rows or all objects. The\n    // full `isMatrix` scan guards the API's data, and here it would only walk every row for nothing.\n    // A row-by-row copy is a full copy: a matrix is two levels deep and its cells are primitives.\n    // `structuredClone` would do the same about 8 times slower (147 ms against 18 ms for 100,000\n    // rows of 10 cells), paying for cycles and special types a datastore matrix never holds.\n    return Array.isArray(data[0])\n        ? (data as DatastoreData).map((row) => row.slice())\n        : objectsToMatrix(fields, data as AnyRecord[]);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,IAAa,mBACT,aACA,SACA,SACM;CACN,MAAM,SAAc,CAAC;CAErB,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACnC,MAAM,OAA6B,CAAC;EAEpC,KAAK,cAAc;EAEnB,QAAQ,SAAS,QAAgB,UAAkB;GAC/C,KAAK,UAAU,KAAK,EAAE,CAAC;EAC3B,CAAC;EAED,OAAO,KAAK,IAAS;CACzB;CAEA,OAAO;AACX;;AAGA,IAAM,YAAY,SACd,MAAM,QAAQ,IAAI,KAAK,KAAK,MAAM,MAAM,OAAO;AA+BnD,SAAgB,eACZ,WACA,aAAkC,UACE;CACpC,MAAM,EAAE,SAAS;CAEjB,IAAI,QAAQ,CAAC,SAAS,IAAI,GACtB,OAAO;EAAE,GAAG;EAAW,QAAQ;EAAc;CAA8B;CAG/E,MAAM,SAAU,QAAQ,CAAC;CACzB,MAAM,SAAU,OAAO,MAAM,CAAC;CAE9B,IAAI,eAAe,UACf,OAAO;EAAE,GAAG;EAAW,QAAQ;EAAS;EAAQ,MAAM;CAAO;CAGjE,OAAO;EACH,GAAG;EACH,QAAQ;EACR;EACA,MAAM,gBAAgB,UAAU,IAAI,QAAQ,MAAM;CACtD;AACJ;;;;;;;;AASA,IAAa,oBACT,cAC+C,UAAU,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCxE,IAAa,mBACT,SACA,SACgB;CAIhB,MAAM,SAAwB,CAAC,QAAQ,MAAM,CAAC;CAE9C,KAAK,MAAM,OAAO,MACd,OAAO,KAAK,QAAQ,KAAW,WAAY,IAAI,WAAW,IAAa,CAAC;CAE5E,OAAO;AACX;;;;;;;;;;;;;;;;;;AAmBA,IAAa,qBACT,cACgB;CAChB,MAAM,EAAE,MAAM,WAAW;CAEzB,IAAI,KAAK,WAAW,GAAG,OAAO,OAAO,SAAS,IAAI,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC;CAOtE,OAAO,MAAM,QAAQ,KAAK,EAAE,IACrB,KAAuB,KAAK,QAAQ,IAAI,MAAM,CAAC,IAChD,gBAAgB,QAAQ,IAAmB;AACrD"}

package/dist/lib/file.d.ts

@@ -0,0 +1,34 @@
+/**
+ * fileToBase64
+ *
+ * The raw base64 `createFile` and `updateFile` take as `data`, from a `File` an `<input
+ * type="file">` gives or any `Blob`. The API stores `data` as given, so the `data:<type>;base64,`
+ * prefix `FileReader` puts in front would be stored as part of the content.
+ *
+ * Read through `FileReader` rather than by encoding the bytes in a loop: the browser encodes
+ * natively, with no binary string built byte by byte for `btoa`. An empty file reads as `data:`
+ * with no comma in Chromium, so a missing comma is empty content — for an empty file only, as
+ * a file with content read that way would otherwise be uploaded empty.
+ *
+ * @param blob - The file.
+ * @returns The content as base64, without a prefix.
+ */
+export declare const fileToBase64: (blob: Blob) => Promise<string>;
+/**
+ * base64ToBlob
+ *
+ * A file's content, as the API returns it in `data`, decoded into a `Blob` byte for byte: to work
+ * on the bytes in code, such as parsing a CSV or unzipping. Not to show the file — the app page's
+ * CSP blocks a `blob:` frame, image or media; use the file's own `url` — and it decodes
+ * synchronously, a byte at a time, so a file of several megabytes is better read through it.
+ *
+ * Without content — a file read without `withData: true` — it warns and gives an empty blob:
+ * `atob(null)` decodes the text "null", three bytes of garbage that would pass for the file.
+ *
+ * @param data - The content as base64, as the hooks return it with `withData: true`.
+ * @param contentType - The file's `content_type`, which becomes the blob's `type`.
+ * @returns The content.
+ * @throws {Error} If `data` is not raw base64.
+ */
+export declare const base64ToBlob: (data: string | null | undefined, contentType: string) => Blob;
+//# sourceMappingURL=file.d.ts.map

package/dist/lib/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/lib/file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,OAAO,CAAC,MAAM,CAgBlD,CAAC;AAEP;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,aAAa,MAAM,KAAG,IAiBnF,CAAC"}

package/dist/lib/file.js

@@ -0,0 +1,63 @@
+//#region src/lib/file.ts
+/**
+* fileToBase64
+*
+* The raw base64 `createFile` and `updateFile` take as `data`, from a `File` an `<input
+* type="file">` gives or any `Blob`. The API stores `data` as given, so the `data:<type>;base64,`
+* prefix `FileReader` puts in front would be stored as part of the content.
+*
+* Read through `FileReader` rather than by encoding the bytes in a loop: the browser encodes
+* natively, with no binary string built byte by byte for `btoa`. An empty file reads as `data:`
+* with no comma in Chromium, so a missing comma is empty content — for an empty file only, as
+* a file with content read that way would otherwise be uploaded empty.
+*
+* @param blob - The file.
+* @returns The content as base64, without a prefix.
+*/
+var fileToBase64 = (blob) => new Promise((resolve, reject) => {
+	const reader = new FileReader();
+	reader.onload = () => {
+		const dataUrl = String(reader.result);
+		const comma = dataUrl.indexOf(",");
+		if (comma !== -1) resolve(dataUrl.slice(comma + 1));
+		else if (blob.size === 0) resolve("");
+		else reject(/* @__PURE__ */ new Error("Unable to read the file: it read as a data URL with no content"));
+	};
+	reader.onerror = () => reject(reader.error ?? /* @__PURE__ */ new Error("Unable to read the file"));
+	reader.readAsDataURL(blob);
+});
+/**
+* base64ToBlob
+*
+* A file's content, as the API returns it in `data`, decoded into a `Blob` byte for byte: to work
+* on the bytes in code, such as parsing a CSV or unzipping. Not to show the file — the app page's
+* CSP blocks a `blob:` frame, image or media; use the file's own `url` — and it decodes
+* synchronously, a byte at a time, so a file of several megabytes is better read through it.
+*
+* Without content — a file read without `withData: true` — it warns and gives an empty blob:
+* `atob(null)` decodes the text "null", three bytes of garbage that would pass for the file.
+*
+* @param data - The content as base64, as the hooks return it with `withData: true`.
+* @param contentType - The file's `content_type`, which becomes the blob's `type`.
+* @returns The content.
+* @throws {Error} If `data` is not raw base64.
+*/
+var base64ToBlob = (data, contentType) => {
+	if (data == null) {
+		console.warn("[apps-sdk] base64ToBlob: the file came without its content; read it with withData: true.");
+		return new Blob([], { type: contentType });
+	}
+	let binary;
+	try {
+		binary = atob(data);
+	} catch (error) {
+		throw new Error("The file's data is not raw base64", { cause: error });
+	}
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return new Blob([bytes], { type: contentType });
+};
+//#endregion
+export { base64ToBlob, fileToBase64 };
+
+//# sourceMappingURL=file.js.map

package/dist/lib/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","names":[],"sources":["../../src/lib/file.ts"],"sourcesContent":["/**\n * fileToBase64\n *\n * The raw base64 `createFile` and `updateFile` take as `data`, from a `File` an `<input\n * type=\"file\">` gives or any `Blob`. The API stores `data` as given, so the `data:<type>;base64,`\n * prefix `FileReader` puts in front would be stored as part of the content.\n *\n * Read through `FileReader` rather than by encoding the bytes in a loop: the browser encodes\n * natively, with no binary string built byte by byte for `btoa`. An empty file reads as `data:`\n * with no comma in Chromium, so a missing comma is empty content — for an empty file only, as\n * a file with content read that way would otherwise be uploaded empty.\n *\n * @param blob - The file.\n * @returns The content as base64, without a prefix.\n */\nexport const fileToBase64 = (blob: Blob): Promise<string> =>\n    new Promise((resolve, reject) => {\n        const reader = new FileReader();\n        reader.onload = () => {\n            const dataUrl = String(reader.result);\n            const comma = dataUrl.indexOf(\",\");\n            if (comma !== -1) {\n                resolve(dataUrl.slice(comma + 1));\n            } else if (blob.size === 0) {\n                resolve(\"\");\n            } else {\n                reject(new Error(\"Unable to read the file: it read as a data URL with no content\"));\n            }\n        };\n        reader.onerror = () => reject(reader.error ?? new Error(\"Unable to read the file\"));\n        reader.readAsDataURL(blob);\n    });\n\n/**\n * base64ToBlob\n *\n * A file's content, as the API returns it in `data`, decoded into a `Blob` byte for byte: to work\n * on the bytes in code, such as parsing a CSV or unzipping. Not to show the file — the app page's\n * CSP blocks a `blob:` frame, image or media; use the file's own `url` — and it decodes\n * synchronously, a byte at a time, so a file of several megabytes is better read through it.\n *\n * Without content — a file read without `withData: true` — it warns and gives an empty blob:\n * `atob(null)` decodes the text \"null\", three bytes of garbage that would pass for the file.\n *\n * @param data - The content as base64, as the hooks return it with `withData: true`.\n * @param contentType - The file's `content_type`, which becomes the blob's `type`.\n * @returns The content.\n * @throws {Error} If `data` is not raw base64.\n */\nexport const base64ToBlob = (data: string | null | undefined, contentType: string): Blob => {\n    if (data == null) {\n        console.warn(\n            \"[apps-sdk] base64ToBlob: the file came without its content; read it with withData: true.\",\n        );\n        return new Blob([], { type: contentType });\n    }\n\n    let binary: string;\n    try {\n        binary = atob(data);\n    } catch (error) {\n        throw new Error(\"The file's data is not raw base64\", { cause: error });\n    }\n    const bytes = new Uint8Array(binary.length);\n    for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);\n    return new Blob([bytes], { type: contentType });\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,IAAa,gBAAgB,SACzB,IAAI,SAAS,SAAS,WAAW;CAC7B,MAAM,SAAS,IAAI,WAAW;CAC9B,OAAO,eAAe;EAClB,MAAM,UAAU,OAAO,OAAO,MAAM;EACpC,MAAM,QAAQ,QAAQ,QAAQ,GAAG;EACjC,IAAI,UAAU,IACV,QAAQ,QAAQ,MAAM,QAAQ,CAAC,CAAC;OAC7B,IAAI,KAAK,SAAS,GACrB,QAAQ,EAAE;OAEV,uBAAO,IAAI,MAAM,gEAAgE,CAAC;CAE1F;CACA,OAAO,gBAAgB,OAAO,OAAO,yBAAS,IAAI,MAAM,yBAAyB,CAAC;CAClF,OAAO,cAAc,IAAI;AAC7B,CAAC;;;;;;;;;;;;;;;;;AAkBL,IAAa,gBAAgB,MAAiC,gBAA8B;CACxF,IAAI,QAAQ,MAAM;EACd,QAAQ,KACJ,0FACJ;EACA,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE,MAAM,YAAY,CAAC;CAC7C;CAEA,IAAI;CACJ,IAAI;EACA,SAAS,KAAK,IAAI;CACtB,SAAS,OAAO;EACZ,MAAM,IAAI,MAAM,qCAAqC,EAAE,OAAO,MAAM,CAAC;CACzE;CACA,MAAM,QAAQ,IAAI,WAAW,OAAO,MAAM;CAC1C,KAAK,IAAI,QAAQ,GAAG,QAAQ,OAAO,QAAQ,SAAS,MAAM,SAAS,OAAO,WAAW,KAAK;CAC1F,OAAO,IAAI,KAAK,CAAC,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;AAClD"}

package/dist/lib/queryClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queryClient.d.ts","sourceRoot":"","sources":["../../src/lib/queryClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAShG,KAAK,oBAAoB,GAAG,YAAY,GAAG,OAAO,CAAC;AACnD,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE;IAClC,KAAK,EAAE,oBAAoB,CAAC;CAC/B,KAAK,aAAa,CAAC,CAAC,CAaZ,CAAC;AAEV;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,iBAAiB,KAAG,WAgBzD,CAAC"}
+{"version":3,"file":"queryClient.d.ts","sourceRoot":"","sources":["../../src/lib/queryClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAShG,KAAK,oBAAoB,GAAG,YAAY,GAAG,OAAO,CAAC;AACnD,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,oBAAoB,CAAA;CAAE,KAAK,aAAa,CAAC,CAAC,CAapF,CAAC;AAEN;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,iBAAiB,KAAG,WAgBzD,CAAC"}

package/dist/lib/queryClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"queryClient.js","names":[],"sources":["../../src/lib/queryClient.ts"],"sourcesContent":["import { QueryClient, type QueryClientConfig, type QueryFunction } from \"@tanstack/react-query\";\n\nasync function throwIfResNotOk(res: Response) {\n    if (!res.ok) {\n        const text = (await res.text()) || res.statusText;\n        throw new Error(`${res.status}: ${text}`);\n    }\n}\n\ntype UnauthorizedBehavior = \"returnNull\" | \"throw\";\nexport const getQueryFn: <T>(options: {\n    on401: UnauthorizedBehavior;\n}) => QueryFunction<T> =\n    ({ on401: unauthorizedBehavior }) =>\n        async ({ queryKey }) => {\n            const res = await fetch(queryKey.join(\"/\") as string, {\n                credentials: \"include\",\n            });\n\n            if (unauthorizedBehavior === \"returnNull\" && res.status === 401) {\n                return null;\n            }\n\n            await throwIfResNotOk(res);\n            return await res.json();\n        };\n\n/**\n * createQueryClient\n *\n * Builds a `QueryClient` carrying the defaults every Everysk app shares: the fetch-based\n * `queryFn` above, no retries, no refetch on focus or interval, and `staleTime: Infinity`.\n *\n * This is a factory rather than the shared instance the template exported. A module-level\n * `new QueryClient()` inside a published package is a single cache shared by every consumer\n * of that copy of the module: it cannot be configured per app, it cannot be reset, and in\n * tests it leaks state from one case into the next. The app owns the instance and passes it\n * to `QueryClientProvider` — `EveryskApp` does this for you when you don't pass one.\n *\n * @param {QueryClientConfig} [config] - Merged over the defaults, one level deep, so passing\n *  `defaultOptions.queries` replaces the whole `queries` object rather than merging into it.\n * @returns {QueryClient} A fresh client.\n */\nexport const createQueryClient = (config?: QueryClientConfig): QueryClient =>\n    new QueryClient({\n        ...config,\n        defaultOptions: {\n            queries: {\n                queryFn: getQueryFn({ on401: \"throw\" }),\n                refetchInterval: false,\n                refetchOnWindowFocus: false,\n                staleTime: Infinity,\n                retry: false,\n            },\n            mutations: {\n                retry: false,\n            },\n            ...config?.defaultOptions,\n        },\n    });\n"],"mappings":";;AAEA,eAAe,gBAAgB,KAAe;CAC1C,IAAI,CAAC,IAAI,IAAI;EACT,MAAM,OAAQ,MAAM,IAAI,KAAK,KAAM,IAAI;EACvC,MAAM,IAAI,MAAM,GAAG,IAAI,OAAO,IAAI,MAAM;CAC5C;AACJ;AAGA,IAAa,cAGR,EAAE,OAAO,2BACN,OAAO,EAAE,eAAe;CACpB,MAAM,MAAM,MAAM,MAAM,SAAS,KAAK,GAAG,GAAa,EAClD,aAAa,UACjB,CAAC;CAED,IAAI,yBAAyB,gBAAgB,IAAI,WAAW,KACxD,OAAO;CAGX,MAAM,gBAAgB,GAAG;CACzB,OAAO,MAAM,IAAI,KAAK;AAC1B;;;;;;;;;;;;;;;;;AAkBR,IAAa,qBAAqB,WAC9B,IAAI,YAAY;CACZ,GAAG;CACH,gBAAgB;EACZ,SAAS;GACL,SAAS,WAAW,EAAE,OAAO,QAAQ,CAAC;GACtC,iBAAiB;GACjB,sBAAsB;GACtB,WAAW;GACX,OAAO;EACX;EACA,WAAW,EACP,OAAO,MACX;EACA,GAAG,QAAQ;CACf;AACJ,CAAC"}
+{"version":3,"file":"queryClient.js","names":[],"sources":["../../src/lib/queryClient.ts"],"sourcesContent":["import { QueryClient, type QueryClientConfig, type QueryFunction } from \"@tanstack/react-query\";\n\nasync function throwIfResNotOk(res: Response) {\n    if (!res.ok) {\n        const text = (await res.text()) || res.statusText;\n        throw new Error(`${res.status}: ${text}`);\n    }\n}\n\ntype UnauthorizedBehavior = \"returnNull\" | \"throw\";\nexport const getQueryFn: <T>(options: { on401: UnauthorizedBehavior }) => QueryFunction<T> =\n    ({ on401: unauthorizedBehavior }) =>\n    async ({ queryKey }) => {\n        const res = await fetch(queryKey.join(\"/\") as string, {\n            credentials: \"include\",\n        });\n\n        if (unauthorizedBehavior === \"returnNull\" && res.status === 401) {\n            return null;\n        }\n\n        await throwIfResNotOk(res);\n        return await res.json();\n    };\n\n/**\n * createQueryClient\n *\n * Builds a `QueryClient` carrying the defaults every Everysk app shares: the fetch-based\n * `queryFn` above, no retries, no refetch on focus or interval, and `staleTime: Infinity`.\n *\n * This is a factory rather than the shared instance the template exported. A module-level\n * `new QueryClient()` inside a published package is a single cache shared by every consumer\n * of that copy of the module: it cannot be configured per app, it cannot be reset, and in\n * tests it leaks state from one case into the next. The app owns the instance and passes it\n * to `QueryClientProvider` — `EveryskApp` does this for you when you don't pass one.\n *\n * @param {QueryClientConfig} [config] - Merged over the defaults, one level deep, so passing\n *  `defaultOptions.queries` replaces the whole `queries` object rather than merging into it.\n * @returns {QueryClient} A fresh client.\n */\nexport const createQueryClient = (config?: QueryClientConfig): QueryClient =>\n    new QueryClient({\n        ...config,\n        defaultOptions: {\n            queries: {\n                queryFn: getQueryFn({ on401: \"throw\" }),\n                refetchInterval: false,\n                refetchOnWindowFocus: false,\n                staleTime: Infinity,\n                retry: false,\n            },\n            mutations: {\n                retry: false,\n            },\n            ...config?.defaultOptions,\n        },\n    });\n"],"mappings":";;AAEA,eAAe,gBAAgB,KAAe;CAC1C,IAAI,CAAC,IAAI,IAAI;EACT,MAAM,OAAQ,MAAM,IAAI,KAAK,KAAM,IAAI;EACvC,MAAM,IAAI,MAAM,GAAG,IAAI,OAAO,IAAI,MAAM;CAC5C;AACJ;AAGA,IAAa,cACR,EAAE,OAAO,2BACV,OAAO,EAAE,eAAe;CACpB,MAAM,MAAM,MAAM,MAAM,SAAS,KAAK,GAAG,GAAa,EAClD,aAAa,UACjB,CAAC;CAED,IAAI,yBAAyB,gBAAgB,IAAI,WAAW,KACxD,OAAO;CAGX,MAAM,gBAAgB,GAAG;CACzB,OAAO,MAAM,IAAI,KAAK;AAC1B;;;;;;;;;;;;;;;;;AAkBJ,IAAa,qBAAqB,WAC9B,IAAI,YAAY;CACZ,GAAG;CACH,gBAAgB;EACZ,SAAS;GACL,SAAS,WAAW,EAAE,OAAO,QAAQ,CAAC;GACtC,iBAAiB;GACjB,sBAAsB;GACtB,WAAW;GACX,OAAO;EACX;EACA,WAAW,EACP,OAAO,MACX;EACA,GAAG,QAAQ;CACf;AACJ,CAAC"}

package/dist/lib/workflowRun.d.ts

@@ -0,0 +1,91 @@
+import type { WebSocketNotification, WebSocketStatus } from "../contexts/webSocketContext/types.d.ts";
+import type { WorkflowExecution } from "../types/workflow.d.ts";
+/** The alert a run hook shows when its failure carries no message of its own. */
+export declare const RUN_FAILED_MESSAGE = "Unable to run the workflow. Please try again.";
+/**
+ * The error a run ends with when its caller stopped it — the screen went away, or the app's own
+ * signal — with that signal's reason as the cause. One class for both phases, the wait and the
+ * result read, so a caller can tell a stop from a failure with `instanceof` rather than by its
+ * message.
+ */
+export declare class WorkflowRunAbortedError extends Error {
+    constructor(reason: unknown);
+}
+export type WorkflowWaitOptions = {
+    /**
+     * How long the run may go without any event before the execution is read anyway, in
+     * milliseconds. Defaults to a minute. It covers a lost event, and a long worker, which sends
+     * nothing while it runs.
+     */
+    silenceMs?: number;
+    /** How long to wait for the run to end before giving up, in milliseconds. Defaults to 5 minutes. */
+    timeoutMs?: number;
+    /**
+     * The first gap between reads after the end event, while the run still reads RUNNING, in
+     * milliseconds. It doubles each time it passes without a new event, up to `silenceMs`.
+     * Defaults to 1 second.
+     */
+    confirmIntervalMs?: number;
+    /**
+     * How long the socket may stay in `error` before the run is given up on as unfollowable, in
+     * milliseconds. Defaults to 30 seconds: socket.io keeps retrying after a failed reconnect, on
+     * a backoff that alone can reach about 7.5 seconds between attempts.
+     */
+    unavailableAfterMs?: number;
+    /** Stops waiting. `useRunWorkflow` also stops when its screen unmounts. */
+    signal?: AbortSignal;
+};
+export type RunWorkflowToEndParams = WorkflowWaitOptions & {
+    /** Starts the run (`POST /workflows/:id/run`) and returns the execution it created. */
+    startRun: () => Promise<WorkflowExecution>;
+    /**
+     * Reads the execution; its `run_status` is what says the run ended, and how. Pass `signal` to
+     * the request, so a timeout or an abort cancels a read in flight.
+     */
+    getExecution: (workflowExecutionId: string, signal: AbortSignal) => Promise<WorkflowExecution>;
+    /** The websocket context's `subscribe`. */
+    subscribeToEvents: (listener: (event: WebSocketNotification) => void) => () => void;
+    /**
+     * The websocket context's `subscribeStatus`, which tells a new listener the current status at
+     * once: that is how the wait learns the status it begins in.
+     */
+    subscribeToStatus: (listener: (status: WebSocketStatus) => void) => () => void;
+};
+/**
+ * runWorkflowToEnd
+ *
+ * Starts a workflow run and waits for it to end, listening to the websocket rather than polling;
+ * the end itself is read from the API. Resolves with the ended execution, whatever its
+ * `run_status` — deciding what counts as success is the caller's.
+ *
+ * The websocket says *when* to read, never *what* happened. The backend publishes a
+ * `WORKER_EXECUTION_*` event per worker and a `WORKFLOW_EXECUTION_COMPLETED|FAILED` one when the
+ * Ender finishes, all on the account's channel. That end event goes out before `run_status` is
+ * written, and its `COMPLETED` is the Ender's status, not the run's: so it triggers a read, and
+ * then more on a short, doubling delay (`confirmIntervalMs`, capped at `silenceMs`) until the run
+ * reads ended — no later event would trigger one.
+ *
+ * Delivery is at most once, with no replay, and the server cuts every socket about once an hour.
+ * So the execution is also read after `silenceMs` without any event of the run, and as soon as
+ * the socket reconnects. A read that fails in a way that may pass (no response, a 5XX, a 429) does
+ * not end the wait — the next trigger reads again — and the last such failure is the cause if the
+ * wait times out, until a read succeeds. Any other failure ends it at once: a 4XX, or anything
+ * that is not a request failure, such as a body that is not the expected JSON.
+ *
+ * The run's end cannot be followed without the socket, so a socket in `error` for
+ * `unavailableAfterMs` — its config failed, or the server dropped it — fails the wait. The run is
+ * held back until the socket is connected, so it is never started unfollowable, and nothing it
+ * publishes goes out before the wait is listening.
+ *
+ * A timeout or an abort stops everything at once through one signal: the wait, the pause between
+ * reads, and the read in flight, whose request is cancelled. The start request is abandoned
+ * rather than cancelled — `startRun` takes no signal — so the run may still begin on the server.
+ *
+ * @param params - The start and read calls, the websocket subscriptions and the wait options.
+ * @returns The execution, once its `run_status` is terminal.
+ * @throws {Error} If a wait option is not a positive number, the run cannot be started or has no
+ *   execution id, a read fails for good, the socket stays unavailable for `unavailableAfterMs`, or
+ *   the wait times out or is aborted (`WorkflowRunAbortedError`, with the signal's reason as the cause).
+ */
+export declare const runWorkflowToEnd: ({ startRun, getExecution, subscribeToEvents, subscribeToStatus, silenceMs, timeoutMs, confirmIntervalMs, unavailableAfterMs, signal, }: RunWorkflowToEndParams) => Promise<WorkflowExecution>;
+//# sourceMappingURL=workflowRun.d.ts.map

package/dist/lib/workflowRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflowRun.d.ts","sourceRoot":"","sources":["../../src/lib/workflowRun.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAChG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,kDAAkD,CAAC;AAUlF;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBAClC,MAAM,EAAE,OAAO;CAI9B;AAmBD,MAAM,MAAM,mBAAmB,GAAG;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG;IACvD,uFAAuF;IACvF,QAAQ,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC3C;;;OAGG;IACH,YAAY,EAAE,CAAC,mBAAmB,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/F,2CAA2C;IAC3C,iBAAiB,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACpF;;;OAGG;IACH,iBAAiB,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAClF,CAAC;AAkIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,gBAAgB,GAAU,wIAUpC,sBAAsB,KAAG,OAAO,CAAC,iBAAiB,CAiEpD,CAAC"}