@vandenberghinc/volt 1.2.6 → 1.2.8

package/backend/dist/esm/backend/src/database/filters/strict_update_filter_test.js

@@ -0,0 +1,415 @@
+// ============================================================================
+// StrictUpdateFilter Tests - Should FAIL (produce TypeScript errors)
+// ============================================================================
+// Test 5: Unknown field in $set
+const failUpdate1 = {
+    $set: {
+        // @ts-expect-error - 'unknown' does not exist in TestSchema
+        unknown: true,
+    }
+};
+// Test 6: Unknown nested field in $set
+const failUpdate2 = {
+    $set: {
+        // @ts-expect-error - 'profile.unknown' is not a valid path
+        'profile.unknown': 'value',
+    }
+};
+// Test 7: Unknown field in $inc
+const failUpdate3 = {
+    $inc: {
+        // @ts-expect-error - 'unknownNumber' does not exist
+        unknownNumber: 1,
+    }
+};
+// Test 8: Using $inc on non-numeric field
+const failUpdate4 = {
+    $inc: {
+        // @ts-expect-error - 'name' is a string, not a number
+        name: 1,
+    }
+};
+// Test 9: Unknown field in $unset
+const failUpdate5 = {
+    $unset: {
+        // @ts-expect-error - 'notAField' does not exist
+        notAField: true,
+    }
+};
+// Test 10: Unknown field in $push
+const failUpdate6 = {
+    $push: {
+        // @ts-expect-error - 'unknownArray' does not exist
+        unknownArray: 'item',
+    }
+};
+// Test 11: Using $push on non-array field
+const failUpdate7 = {
+    $push: {
+        // @ts-expect-error - 'name' is not an array
+        name: 'value',
+    }
+};
+// Test 12: Unknown field in $pull
+const failUpdate8 = {
+    $pull: {
+        // @ts-expect-error - 'fakeArray' does not exist
+        fakeArray: 'item',
+    }
+};
+// Test 13: Unknown field in $rename
+const failUpdate9 = {
+    $rename: {
+        // @ts-expect-error - 'oldField' does not exist
+        oldField: 'newField',
+    }
+};
+// Test 14: Unknown field in $currentDate
+const failUpdate10 = {
+    $currentDate: {
+        // @ts-expect-error - 'timestamp' does not exist
+        timestamp: true,
+    }
+};
+// Test 15: Using $currentDate on non-date field
+const failUpdate11 = {
+    $currentDate: {
+        // @ts-expect-error - 'name' is not a Date field
+        name: true,
+    }
+};
+// Test 16: Unknown field in $mul
+const failUpdate12 = {
+    $mul: {
+        // @ts-expect-error - 'multiplier' does not exist
+        multiplier: 2,
+    }
+};
+// Test 17: Using $mul on non-numeric field
+const failUpdate13 = {
+    $mul: {
+        // @ts-expect-error - 'isActive' is boolean, not number
+        isActive: 2,
+    }
+};
+// Test 18: Unknown field in $min
+const failUpdate14 = {
+    $min: {
+        // @ts-expect-error - 'minimum' does not exist
+        minimum: 10,
+    }
+};
+// Test 19: Unknown field in $max
+const failUpdate15 = {
+    $max: {
+        // @ts-expect-error - 'maximum' does not exist
+        maximum: 100,
+    }
+};
+// Test 20: Unknown field in $addToSet
+const failUpdate16 = {
+    $addToSet: {
+        // @ts-expect-error - 'collection' does not exist
+        collection: 'item',
+    }
+};
+// Test 21: Using $pop on non-array field
+const failUpdate17 = {
+    $pop: {
+        // @ts-expect-error - 'age' is not an array
+        age: 1,
+    }
+};
+// Test 22: Unknown field in $pullAll
+const failUpdate18 = {
+    $pullAll: {
+        // @ts-expect-error - 'list' does not exist
+        list: ['item1', 'item2'],
+    }
+};
+// Test 23: Unknown field in $bit
+const failUpdate19 = {
+    $bit: {
+        // @ts-expect-error - 'bitField' does not exist
+        bitField: { and: 5 },
+    }
+};
+// Test 24: Using $bit on non-numeric field
+const failUpdate20 = {
+    $bit: {
+        // @ts-expect-error - 'name' is not a number
+        name: { or: 3 },
+    }
+};
+// ============================================================================
+// Valid Tests - Should PASS (no TypeScript errors)
+// ============================================================================
+// Valid $set update
+const validUpdate1 = {
+    $set: {
+        name: 'Jane',
+        age: 25,
+        'profile.email': 'jane@example.com',
+        'profile.address.street': '123 Main St',
+    }
+};
+// Valid $inc update
+const validUpdate2 = {
+    $inc: {
+        age: 1,
+        'profile.address.zip': 100,
+    }
+};
+// Valid $push and $pull
+const validUpdate3 = {
+    $push: {
+        tags: 'new-tag',
+        scores: 95,
+    },
+    $pull: {
+        tags: 'old-tag',
+    }
+};
+// Valid $unset
+const validUpdate4 = {
+    $unset: {
+        description: true,
+        deletedAt: '',
+    }
+};
+// Valid $currentDate
+const validUpdate5 = {
+    $currentDate: {
+        createdAt: true,
+        deletedAt: { $type: 'date' },
+    }
+};
+// Valid $min and $max
+const validUpdate6 = {
+    $min: {
+        age: 0,
+    },
+    $max: {
+        age: 120,
+    }
+};
+// Valid $mul
+const validUpdate7 = {
+    $mul: {
+        age: 1.5,
+        'profile.address.zip': 2,
+    }
+};
+// Valid $rename
+const validUpdate8 = {
+    $rename: {
+        name: 'fullName',
+        'profile.email': 'contact',
+    }
+};
+// Valid $addToSet
+const validUpdate9 = {
+    $addToSet: {
+        tags: 'unique-tag',
+        scores: { $each: [100, 95, 90] },
+    }
+};
+// Valid $pop
+const validUpdate10 = {
+    $pop: {
+        tags: 1,
+        scores: -1,
+    }
+};
+// Valid $pullAll
+const validUpdate11 = {
+    $pullAll: {
+        tags: ['tag1', 'tag2'],
+        scores: [0, 50],
+    }
+};
+// Valid $bit
+const validUpdate12 = {
+    $bit: {
+        age: { and: 5 },
+        'profile.address.zip': { or: 100 },
+    }
+};
+// Valid complex update with multiple operators
+const validUpdate13 = {
+    $set: {
+        name: 'Updated Name',
+        'profile.email': 'new@example.com',
+    },
+    $inc: {
+        age: 1,
+    },
+    $push: {
+        tags: 'new',
+    },
+    $unset: {
+        description: true,
+    },
+    $currentDate: {
+        createdAt: true,
+    }
+};
+// Valid $setOnInsert
+const validUpdate14 = {
+    $setOnInsert: {
+        // id: 'new-id',
+        name: 'Default Name',
+        age: 0,
+        'profile.email': 'default@example.com',
+    }
+};
+// ============================================================================
+// ADDITIONAL NEGATIVE TESTS (Should FAIL)
+// ============================================================================
+// Wrong value type pushed into number[] array
+const failUpdate21 = {
+    $push: {
+        // @ts-expect-error - scores is number[], cannot push string
+        scores: 'oops',
+    }
+};
+// Wrong $each element type in $addToSet for number[]
+const failUpdate22 = {
+    $addToSet: {
+        // @ts-expect-error - scores is number[], $each expects number[]
+        scores: { $each: ['100'] },
+    }
+};
+// Wrong $type option for $currentDate
+const failUpdate23 = {
+    $currentDate: {
+        // @ts-expect-error - only 'date' | 'timestamp' are allowed
+        createdAt: { $type: 'now' },
+    }
+};
+// Wrong value for $unset (must be '' | true | 1)
+const failUpdate24 = {
+    $unset: {
+        // @ts-expect-error - invalid unset spec
+        name: 2,
+    }
+};
+// Wrong value for $pop (must be 1 or -1)
+const failUpdate25 = {
+    $pop: {
+        // @ts-expect-error - only 1 or -1 are allowed
+        tags: 0,
+    }
+};
+// ============================================================================
+// ADDITIONAL POSITIVE TESTS (Should PASS)
+// ============================================================================
+// $push with $each on string[]
+const validUpdate15 = {
+    $push: {
+        tags: { $each: ['x', 'y'] },
+    }
+};
+// $addToSet for array of objects
+const validUpdate16 = {
+    $addToSet: {
+        items: { id: 'sku-1', quantity: 2 },
+    }
+};
+// $addToSet with $each for array of objects
+const validUpdate17 = {
+    $addToSet: {
+        items: {
+            $each: [
+                { id: 'sku-2', quantity: 1 },
+                { id: 'sku-3', quantity: 5 },
+            ]
+        }
+    }
+};
+// $pull using operator on primitive array
+const validUpdate18 = {
+    $pull: {
+        tags: { $in: ['legacy', 'old'] },
+        scores: { $gt: 100 },
+    }
+};
+// $min/$max on Date field
+const validUpdate19 = {
+    $min: { createdAt: new Date(0) },
+    $max: { createdAt: new Date() },
+};
+// $rename on deep nested field
+const validUpdate20 = {
+    $rename: {
+        'profile.address.street': 'streetLine1',
+    }
+};
+// StrictUpdateFilter → mongodb.UpdateFilter
+const strictUpdateForCast = {
+    $set: { name: 'Cast OK' },
+    $inc: { age: 1 },
+};
+const mongoUpdateCast = strictUpdateForCast;
+const strictUpdateForUpdateMany = {
+    $set: { name: 'Overload OK' },
+    $inc: { age: 2 },
+};
+void colX.updateMany({ id: 'abc' }, strictUpdateForUpdateMany, {});
+function update_test_1(filter, update_filter) {
+    colX.updateMany(filter, update_filter, {});
+}
+const okStrictUpdateConcrete = {
+    $set: { name: "Overload OK" },
+    $inc: { age: 2 },
+};
+function genericSaveRepro(filter, op) {
+    const bulkOp = {
+        updateOne: {
+            filter,
+            update: op, // <- This is where TS2322 shows up pre-fix
+            upsert: true,
+        },
+    };
+    // @ts-expect-error – pre-fix: StrictUpdateFilter<Data> not assignable to UpdateFilter<Data>
+    acceptsBulk(bulkOp);
+    // Also directly:
+    // @ts-expect-error – pre-fix: same reason
+    const _direct = bulkOp;
+    // And findOneAndUpdate:
+    const colGeneric = null;
+    // @ts-expect-error – pre-fix: StrictUpdateFilter<Data> not assignable to UpdateFilter<Data>
+    colGeneric.findOneAndUpdate(filter, op);
+}
+// ----- $currentDate guardrails still behave -----
+{
+    // OK: $currentDate on date field
+    const okCD = {
+        $currentDate: { "createdAt": true },
+    };
+    const badCD = {
+        // @ts-expect-error – should be rejected: $currentDate on non-date field
+        $currentDate: { "name": true },
+    };
+}
+const ok_query = {
+    $set: {
+        max: 0,
+        interval: 0,
+    },
+    $setOnInsert: {
+        usage: 0,
+        start: 0,
+    },
+};
+export {};
+// ============================================================================
+// $set + $concatArray
+// const u: StrictUpdateFilter<TestSchema> = {
+//     $set: {
+//         items: { $concatArrays: [
+//             { $ifNull: ["$items", []] },
+//             [{ id: "x", quantity: 1 }]]
+//         }
+//     }
+// };

package/backend/dist/esm/backend/src/database/flatten.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh.
+ */
+/**
+ * Flatten a nested object to a flat `key.subkey` like object, suitable for {@link set} and {@link save} $inc operations.
+ * @param obj The object to flatten.
+ * @param prefix The prefix to use for the keys, used for recursive calls, new keys will be formatted as `{prefix}.key`.
+ * @returns A flat object with keys in the format `key.subkey`.
+ * @example
+ * const nested = { a: { b: 1, c: { d: 2 } }, e: 3 };
+ * const flat = flatten(nested);
+ * // flat = { 'a.b': 1, 'a.c.d': 2, 'e': 3 }
+ *
+ * @nav Database
+ * @docs
+ */
+export declare function flatten<T extends Record<string, any>>(obj: T, prefix?: string): FlattenToDotNotation<T>;
+export declare function flatten<T extends Record<string, any>, const Prefix extends string>(obj: T, prefix: Prefix): FlattenToDotNotation<T, Prefix>;
+/**
+ * Convert union to intersection
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+/**
+ * Check if a type should be flattened (is a plain object, not a primitive or array)
+ */
+type IsPlainObject<T> = T extends string | number | boolean | bigint | symbol | null | undefined | Date | RegExp | Function | any[] ? false : T extends object ? true : false;
+/** Make all properties optional (used when recursing through optional parents) */
+type MakeOptional<T> = {
+    [P in keyof T]?: T[P];
+};
+/** Depth decrementer for 25 levels: Prev25[N] = N - 1, Prev25[0] = never */
+type Prev25 = [
+    never,
+    0,
+    1,
+    2,
+    3,
+    4,
+    5,
+    6,
+    7,
+    8,
+    9,
+    10,
+    11,
+    12,
+    13,
+    14,
+    15,
+    16,
+    17,
+    18,
+    19,
+    20,
+    21,
+    22,
+    23,
+    24,
+    25
+];
+/** Remove undefined from a type (used before object checks) */
+type NonU<T> = Exclude<T, undefined>;
+/**
+ * Create dot notation paths from an object type.
+ * - Handles optional parents by making *all* their dotted children optional.
+ * - Stops recursing at depth 25.
+ */
+export type FlattenToDotNotation<T, Path extends string = "", D extends number = 25> = [
+    D
+] extends [never] ? {} : T extends object ? UnionToIntersection<{
+    [K in keyof T]-?: K extends string | number ? (T[K] extends infer Raw ? (IsPlainObject<NonU<Raw>> extends true ? (undefined extends Raw ? MakeOptional<FlattenToDotNotation<NonU<Raw>, Path extends "" ? `${K}` : `${Path}.${K}`, Prev25[D]>> : FlattenToDotNotation<NonU<Raw>, Path extends "" ? `${K}` : `${Path}.${K}`, Prev25[D]>) : (undefined extends Raw ? {
+        [P in (Path extends "" ? `${K}` : `${Path}.${K}`)]?: NonU<Raw>;
+    } : {
+        [P in (Path extends "" ? `${K}` : `${Path}.${K}`)]: Raw;
+    })) : never) : never;
+}[keyof T]> : T;
+export {};

package/backend/dist/esm/backend/src/database/flatten.js

@@ -0,0 +1,22 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh.
+ */
+import * as vlib from "@vandenberghinc/vlib";
+export function flatten(obj, prefix = "") {
+    if (typeof obj !== "object" || obj == null || Array.isArray(obj)) {
+        vlib.schema.throw_invalid_type("obj", obj, "object", true);
+    }
+    const result = {};
+    for (const key in obj) {
+        if (!Object.hasOwn(obj, key))
+            continue; // ES2022
+        if (vlib.object.is_plain(obj[key])) {
+            Object.assign(result, flatten(obj[key], prefix ? `${prefix}.${key}` : key));
+        }
+        else {
+            result[prefix ? `${prefix}.${key}` : key] = obj[key];
+        }
+    }
+    return result;
+}

package/backend/dist/esm/backend/src/database/flatten_test.d.ts

@@ -0,0 +1 @@
+export {};

package/backend/dist/esm/backend/src/database/flatten_test.js

@@ -0,0 +1,174 @@
+// Valid assignments
+const validSimple1 = {
+    x: true,
+    "y.z": 42
+};
+const validSimple2 = {
+    x: false,
+    "y.z": -100
+};
+// Invalid assignments - should produce TypeScript errors
+// @ts-expect-error - missing required field "y.z"
+const invalidSimple1 = {
+    x: true
+};
+const invalidSimple2 = {
+    x: true,
+    // @ts-expect-error - "y.z" should be number, not string
+    "y.z": "not a number"
+};
+const invalidSimple3 = {
+    x: true,
+    "y.z": 42,
+    // @ts-expect-error - "unknown" field doesn't exist
+    unknown: "field"
+};
+// Valid assignments
+const validDeep1 = {
+    "level1.level2.level3.level4.value": "test",
+    "level1.level2.level3.level4.count": 10,
+    "level1.level2.level3.flag": true,
+    "level1.sibling": "hello",
+    top: 5
+};
+// Invalid assignments
+// @ts-expect-error - missing required fields
+const invalidDeep1 = {
+    top: 5
+};
+const invalidDeep2 = {
+    "level1.level2.level3.level4.value": "test",
+    "level1.level2.level3.level4.count": 10,
+    "level1.level2.level3.flag": true,
+    "level1.sibling": "hello",
+    top: 5,
+    // @ts-expect-error - "level1.level2.unknown" doesn't exist
+    "level1.level2.unknown": "nope"
+};
+// Valid assignments
+const validMixed1 = {
+    name: "John",
+    age: 30,
+    tags: ["user", "admin"],
+    "profile.email": "john@example.com",
+    "profile.nested_tags": ["user", "admin"],
+    "profile.settings.theme": "dark",
+    "profile.settings.notifications": true
+};
+const validMixed2 = {
+    name: "Jane",
+    age: 25,
+    tags: ["x"],
+    "profile.nested_tags": ["x"],
+    "profile.email": "jane@example.com",
+    "profile.settings.theme": "light",
+    "profile.settings.notifications": false,
+    "metadata.created": new Date(),
+    "metadata.updated": new Date()
+};
+// Invalid assignments
+const invalidMixed1 = {
+    name: "Test",
+    age: 20,
+    // @ts-expect-error - tags should be string[], not number[]
+    tags: [1, 2, 3],
+    "profile.email": "test@example.com",
+    "profile.settings.theme": "dark",
+    "profile.settings.notifications": false,
+};
+const invalidMixed1_1 = {
+    name: "Test",
+    age: 20,
+    "profile.email": "test@example.com",
+    "profile.settings.theme": "dark",
+    "profile.settings.notifications": false,
+    // @ts-expect-error - "profile.UNKNOWN_nested_tags" does not exist
+    "profile.UNKNOWN_nested_tags": ["user", "admin"],
+};
+const invalidMixed2 = {
+    name: "Test",
+    age: 20,
+    tags: ["tag"],
+    "profile.email": "test@example.com",
+    // @ts-expect-error - theme must be "dark" | "light", not "blue"
+    "profile.settings.theme": "blue",
+    "profile.settings.notifications": false
+};
+// Valid complex assignment
+const validUser = {
+    id: "user123",
+    "personal.firstName": "John",
+    "personal.lastName": "Doe",
+    "personal.dateOfBirth": new Date("1990-01-01"),
+    "personal.contact.email": "john@example.com",
+    "personal.contact.address.street": "123 Main St",
+    "personal.contact.address.city": "New York",
+    "personal.contact.address.country": "USA",
+    "personal.contact.address.postal.code": "10001",
+    "preferences.language": "en",
+    "preferences.timezone": "America/New_York",
+    "preferences.privacy.shareEmail": true,
+    "preferences.privacy.sharePhone": false,
+    "preferences.privacy.visibility": "friends",
+    "stats.loginCount": 42,
+    "stats.lastLogin": new Date(),
+    "stats.accountAge": 365
+};
+// Invalid complex assignments
+const invalidUser1 = {
+    id: "user123",
+    "personal.firstName": "John",
+    "personal.lastName": "Doe",
+    "personal.dateOfBirth": new Date("1990-01-01"),
+    "personal.contact.email": "john@example.com",
+    "personal.contact.address.street": "123 Main St",
+    "personal.contact.address.city": "New York",
+    "personal.contact.address.country": "USA",
+    "personal.contact.address.postal.code": "10001",
+    // @ts-expect-error - language must be "en" | "es" | "fr", not "de"
+    "preferences.language": "de",
+    "preferences.timezone": "America/New_York",
+    "preferences.privacy.shareEmail": true,
+    "preferences.privacy.sharePhone": false,
+    "preferences.privacy.visibility": "friends",
+    "stats.loginCount": 42,
+    "stats.lastLogin": new Date(),
+    "stats.accountAge": 365
+};
+const invalidUser2 = {
+    id: "user123",
+    "personal.firstName": "John",
+    "personal.lastName": "Doe",
+    "personal.dateOfBirth": new Date("1990-01-01"),
+    "personal.contact.email": "john@example.com",
+    "personal.contact.address.street": "123 Main St",
+    "personal.contact.address.city": "New York",
+    "personal.contact.address.country": "USA",
+    "personal.contact.address.postal.code": "10001",
+    "preferences.language": "en",
+    "preferences.timezone": "America/New_York",
+    "preferences.privacy.shareEmail": true,
+    "preferences.privacy.sharePhone": false,
+    // @ts-expect-error - visibility must be "public" | "private" | "friends", not "hidden"
+    "preferences.privacy.visibility": "hidden",
+    "stats.loginCount": 42,
+    "stats.lastLogin": new Date(),
+    "stats.accountAge": 365
+};
+const validVeryDeep = {
+    "l1.l2.l3.l4.l5.l6.l7.l8.l9.l10.l11.l12.l13.l14.l15.l16.l17.l18.l19.l20.l21.l22.l23.l24.l25.value": "deep!"
+};
+// Both should be valid
+const validOptional1 = {
+    required: "yes"
+};
+const validOptional2 = {
+    required: "yes",
+    "optional.nested.value": 42
+};
+// Invalid optional usage
+// @ts-expect-error - "required" is missing
+const invalidOptional = {
+    "optional.nested.value": 42
+};
+export {};