Feature srandom - A seeded random number

A function generating seeded random numbers, allowing for sorting lists in a random, but predictively fashion.

Author: holroy

docs/docs/reference/functions.md

@@ -272,7 +272,17 @@ maxby([1, 2, 3], (k) => 0 - k) => 1
 maxby(this.file.tasks, (k) => k.due) => (latest due)
 ```
 
---
+### `srandom([number|text])`
+
+Returns a seeded random number based on either a `number` or a `text`. Repeated calls to `srandom()` with the same seed, gives the same sequence of random numbers. This is useful in a query when combined with sorting a list on this sequence, and then doing a `LIMIT` on that sequence, to get a given set of random items for that seed.
+
+In other words, if used with a date, you can sort your list/quotes/... and get a random element from that list, and it'll change when your date string changes. This way you can get a random item each day, each hour, etc based on what you use as the seed.
+
+```js
+srandom(12345) x3 = 0.6462731098290533, 0.5638589910231531, 0.35898207360878587 
+srandom("2024-02-28") x3 = 0.44641065830364823, 0.988620902877301, 0.01667086035013199 
+```
+---
 
 ## Objects, Arrays, and String Operations
 

docs/docs/resources/examples.md

@@ -83,3 +83,18 @@ List all files which have a date in their title (of the form `yyyy-mm-dd`), and
 === "Output"
     - [2021-08-07](#): August 07, 2021
     - [2020-08-10](#): August 10, 2020
+
+---
+
+Get three random links from your vault, which changes every day, but are consistent throughout the day. Similar queries can also be used to get random quotes, or other random items to your liking. 
+
+=== "Query"
+   ```sql
+   LIST 
+   FLATTEN srandom(dateformat(date(today), "yyyy-MM-dd")) as randomValue
+   SORT randomValue
+   LIMIT 3
+   ```
+=== "Output"
+
+Three random links from your vault, where on any given day the three links are consistently the same. The only thing capable of changing it, is changing the source list from where you're pulling the random items.

src/expression/functions.ts

@@ -9,6 +9,7 @@ import { Fields } from "./field";
 import { EXPRESSION } from "./parse";
 import { escapeRegex } from "util/normalize";
 import { DataArray } from "api/data-array";
+import { executeSrandom } from "util/srandom";
 
 /**
  * A function implementation which takes in a function context and a variable number of arguments. Throws an error if an
@@ -441,6 +442,15 @@ export namespace DefaultFunctions {
         .add2("null", "function", (_arr, _func, _ctx) => null)
         .build();
 
+    export const srandom: FunctionImpl = new FunctionBuilder("srandom")
+        .add1("number", (seed, ctx) => {
+            return executeSrandom(seed.toString(), ctx);
+        })
+        .add1("string", (seed, ctx) => {
+            return executeSrandom(seed, ctx);
+        })
+        .build();
+
     export const striptime = new FunctionBuilder("striptime")
         .add1("date", d => DateTime.fromObject({ year: d.year, month: d.month, day: d.day }))
         .add1("null", _n => null)
@@ -861,6 +871,7 @@ export const DEFAULT_FUNCTIONS: Record<string, FunctionImpl> = {
     max: DefaultFunctions.max,
     minby: DefaultFunctions.minby,
     maxby: DefaultFunctions.maxby,
+    srandom: DefaultFunctions.srandom,
 
     // String operations.
     regexreplace: DefaultFunctions.regexreplace,

src/query/engine.ts

@@ -11,6 +11,7 @@ import { Field, Fields } from "expression/field";
 import { QuerySettings } from "settings";
 import { DateTime } from "luxon";
 import { SListItem } from "data-model/serialized/markdown";
+import { randomUUID } from "crypto";
 
 function iden<T>(x: T): T {
     return x;
@@ -297,6 +298,7 @@ export async function executeList(
     // Extract information about the origin page to add to the root context.
     let rootContext = new Context(defaultLinkHandler(index, origin), settings, {
         this: index.pages.get(origin)?.serialize(index) ?? {},
+        queryUUID: randomUUID(),
     });
 
     let targetField = (query.header as ListQuery).format;
@@ -339,6 +341,7 @@ export async function executeTable(
     // Extract information about the origin page to add to the root context.
     let rootContext = new Context(defaultLinkHandler(index, origin), settings, {
         this: index.pages.get(origin)?.serialize(index) ?? {},
+        queryUUID: randomUUID(),
     });
 
     let targetFields = (query.header as TableQuery).fields;
@@ -419,6 +422,7 @@ export async function executeTask(
     // Extract information about the origin page to add to the root context.
     let rootContext = new Context(defaultLinkHandler(index, origin), settings, {
         this: index.pages.get(origin)?.serialize(index) ?? {},
+        queryUUID: randomUUID(),
     });
 
     return executeCore(incomingTasks, rootContext, query.operations).map(core => {
@@ -441,6 +445,7 @@ export function executeInline(
 ): Result<Literal, string> {
     return new Context(defaultLinkHandler(index, origin), settings, {
         this: index.pages.get(origin)?.serialize(index) ?? {},
+        queryUUID: randomUUID(),
     }).evaluate(field);
 }
 
@@ -481,6 +486,7 @@ export async function executeCalendar(
     // Extract information about the origin page to add to the root context.
     let rootContext = new Context(defaultLinkHandler(index, origin), settings, {
         this: index.pages.get(origin)?.serialize(index) ?? {},
+        queryUUID: randomUUID(),
     });
 
     let targetField = (query.header as CalendarQuery).field.field;

src/test/function/aggregation.test.ts

@@ -1,4 +1,5 @@
-import { expectEvals } from "test/common";
+import { EXPRESSION } from "expression/parse";
+import { expectEvals, simpleContext } from "test/common";
 
 describe("map()", () => {
     test("empty list", () => expectEvals("map([], (k) => 6)", []));
@@ -39,6 +40,20 @@ describe("maxby()", () => {
     test("multiple", () => expectEvals("maxby([1, 2, 3], (k) => 0 - k)", 1));
 });
 
+describe("srandom()", () => {
+    let context = simpleContext().set("queryUUID", "abcdef-1234");
+    test("12345", () =>
+        expect(
+            context.tryEvaluate(EXPRESSION.field.tryParse("list(srandom(12345), srandom(12345), srandom(12345))"))
+        ).toEqual([0.6462731098290533, 0.5638589910231531, 0.35898207360878587]));
+    test('"2024-02-28"', () =>
+        expect(
+            context.tryEvaluate(
+                EXPRESSION.field.tryParse('list(srandom("2024-02-28"), srandom("2024-02-28"), srandom("2024-02-28"))')
+            )
+        ).toEqual([0.44641065830364823, 0.988620902877301, 0.01667086035013199]));
+});
+
 describe("sum()", () => {
     test("number list", () => expectEvals("sum([2, 3, 1])", 6));
     test("string list", () => expectEvals('sum(["a", "b", "c"])', "abc"));

src/util/srandom.ts

@@ -0,0 +1,59 @@
+import { Context } from "expression/context";
+
+/* This seeded random generator is based upon this stackoverflow answer:
+ *   https://stackoverflow.com/a/47593316
+ *
+ *  And the sfc32() and cyrb128() functions copied directrly from it,
+ *  so thanks to https://stackoverflow.com/users/815680/bryc
+ */
+
+function sfc32(a: number, b: number, c: number, d: number): () => number {
+    return function (): number {
+        a |= 0;
+        b |= 0;
+        c |= 0;
+        d |= 0;
+        var t = (((a + b) | 0) + d) | 0;
+        d = (d + 1) | 0;
+        a = b ^ (b >>> 9);
+        b = (c + (c << 3)) | 0;
+        c = (c << 21) | (c >>> 11);
+        c = (c + t) | 0;
+        return (t >>> 0) / 4294967296;
+    };
+}
+
+function cyrb128(str: string): number[] {
+    let h1 = 1779033703,
+        h2 = 3144134277,
+        h3 = 1013904242,
+        h4 = 2773480762;
+    for (let i = 0, k; i < str.length; i++) {
+        k = str.charCodeAt(i);
+        h1 = h2 ^ Math.imul(h1 ^ k, 597399067);
+        h2 = h3 ^ Math.imul(h2 ^ k, 2869860233);
+        h3 = h4 ^ Math.imul(h3 ^ k, 951274213);
+        h4 = h1 ^ Math.imul(h4 ^ k, 2716044179);
+    }
+    h1 = Math.imul(h3 ^ (h1 >>> 18), 597399067);
+    h2 = Math.imul(h4 ^ (h2 >>> 22), 2869860233);
+    h3 = Math.imul(h1 ^ (h3 >>> 17), 951274213);
+    h4 = Math.imul(h2 ^ (h4 >>> 19), 2716044179);
+    (h1 ^= h2 ^ h3 ^ h4), (h2 ^= h1), (h3 ^= h1), (h4 ^= h1);
+    return [h1 >>> 0, h2 >>> 0, h3 >>> 0, h4 >>> 0];
+}
+
+/* Return the unique srandom function for a given query,
+ * using the provided seed
+ */
+export function executeSrandom(seed: string, ctx: Context): number {
+    const internalKey = (ctx.get("queryUUID") as string) + "§" + seed;
+
+    // If key not present, generate new srandom function
+    if (!ctx.globals.hasOwnProperty(internalKey)) {
+        const [a, b, c, d] = cyrb128(seed);
+        ctx.set(internalKey, sfc32(a, b, c, d));
+    }
+
+    return (ctx.get(internalKey) as () => number)();
+}