@faybl/utils 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @faybl/utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generic JavaScript for Faybl services and web apps.
+
+```
+npm install @faybl/utils
+```
+
+## History
+
+`fetchHistory` reads a channel's history through a faybl-client as an array in
+ascending time, each point with `ts` and `pl`, which is what a chart draws.
+
+```js
+import { fetchHistory, fetchHistoryLast } from '@faybl/utils';
+
+const { data } = await fetchHistory({ client, rid, from, to });
+const newest = await fetchHistoryLast({ client, rid });
+```
+
+It decides `ascending` and `reverse` for data-history from the range:
+
+| Asked for                    | Returns                                           |
+| ---------------------------- | ------------------------------------------------- |
+| `from`, with or without `to` | the range, from its start                         |
+| `limit` and `from`           | the first `limit` points from `from`              |
+| `limit` without `from`       | the newest `limit` points, before `to` when given |
+| nothing                      | from the oldest point                             |
+
+`samplingInterval`, `downsamplingMethod` and `timeZone` are passed on. Empty
+values are left out, and nothing else reaches data-history.
+
+`fetchHistoryLast` is the newest point, before `to` when given, or `undefined`.

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@faybl/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Generic JavaScript for Faybl services and web apps",
+  "license": "TBD",
+  "author": "Arcturitech",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/arcturitech/faybl/utils/utils-js.git",
+    "directory": "packages/utils"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/history.js

@@ -0,0 +1,57 @@
+const readOptionKeys = [
+  'from',
+  'to',
+  'limit',
+  'samplingInterval',
+  'downsamplingMethod',
+  'timeZone',
+];
+
+// Empty values are left out: forms hand over '' for a bound nobody set.
+const givenOptions = (params) =>
+  Object.fromEntries(readOptionKeys.filter((key) => params[key]).map((key) => [key, params[key]]));
+
+// From `from`, or with no limit, an ascending read is already in order. A limit
+// without `from` must take the newest points, so that read is descending and
+// reversed back.
+const readOrder = ({ from, limit }) => {
+  const ascending = Boolean(from || !limit);
+  return { ascending, reverse: !ascending };
+};
+
+/**
+ * Reads a channel's history as an array in ascending time, each point with
+ * `ts` and `pl`. A `limit` without `from` takes the newest points.
+ * @param {object} params
+ * @param {object} params.client faybl-client to read through
+ * @param {string} params.rid rid of the channel
+ * @param {string} [params.from] ISO timestamp the range starts at
+ * @param {string} [params.to] ISO timestamp the range ends at
+ * @param {number} [params.limit] Most points to return
+ * @param {number} [params.samplingInterval] Downsampling interval in seconds
+ * @param {string} [params.downsamplingMethod] How a sampling interval is reduced
+ * @param {string} [params.timeZone] Time zone of the returned timestamps
+ * @returns {Promise<{ count: number, timeZone: string, data: Array<{ ts: string, pl: unknown }> }>}
+ */
+export const fetchHistory = (params = {}) => {
+  const { client, rid } = params;
+  if (!rid) return Promise.reject(Error('Missing rid'));
+  if (!client) return Promise.reject(Error('Missing client'));
+  return client.channel.read({
+    rid,
+    projection: ['ts', 'pl'],
+    ...givenOptions(params),
+    ...readOrder(params),
+  });
+};
+
+/**
+ * The newest point of a channel, or the newest before `to`; undefined when
+ * there is none.
+ * @param {object} params Same as for `fetchHistory`, without `from` and `limit`
+ * @returns {Promise<{ ts: string, pl: unknown } | undefined>}
+ */
+export const fetchHistoryLast = async (params = {}) => {
+  const { data: [point] = [] } = await fetchHistory({ ...params, limit: 1 });
+  return point;
+};

package/src/index.js

@@ -0,0 +1 @@
+export { fetchHistory, fetchHistoryLast } from './history.js';