@adobe/data 0.2.0 → 0.2.2

package/src/perftest/perf-test.ts

@@ -1,193 +0,0 @@
-/*MIT License
-
-© Copyright 2025 Adobe. All rights reserved.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.*/
-interface PerfResults {
-  memoryKb: number;
-  timeMs: number;
-  result: any;
-  flops: number;
-}
-
-declare global {
-  interface Performance {
-    measureUserAgentSpecificMemory?: () => { bytes: number };
-    memory?: { usedJSHeapSize: number };
-  }
-}
-
-export interface PerformanceTest {
-  setup: (n: number) => Promise<void>;
-  run: () => any;
-  getVisibleEnabledPositions?: () => number[];
-  type: "create" | "move";
-  cleanup: () => Promise<void>;
-}
-
-const typeToFlops = {
-  create: 10,
-  move: 3 / 4,
-} as const satisfies Record<PerformanceTest["type"], number>;
-
-function isPerformanceTest(obj: any): obj is PerformanceTest {
-  return (
-    typeof obj.setup === "function" &&
-    typeof obj.run === "function" &&
-    typeof obj.cleanup === "function"
-  );
-}
-
-function getMemory() {
-  //  if in the browser, try to get browser memory usage
-  if (typeof window !== "undefined") {
-    return performance.memory?.usedJSHeapSize ?? 0;
-  }
-
-  return performance.measureUserAgentSpecificMemory?.().bytes ?? 0;
-}
-
-function getTime() {
-  return performance.now();
-}
-
-function garbageCollect() {
-  if (typeof globalThis.gc === "function") {
-    globalThis.gc();
-  }
-}
-
-export async function runTests(
-  testSuites: Record<string, Record<string, PerformanceTest>>,
-) {
-  console.log("Starting Tests:");
-  const allResults: Record<string, Record<string, PerfResults[]>> = {};
-  const display = (name: string) => name.replace(/_/g, " ");
-  for (const [suite, tests] of Object.entries(testSuites)) {
-    console.log(`- ${display(suite)}...`);
-    const suiteResults = (allResults[suite] = {} as Record<
-      string,
-      PerfResults[]
-    >);
-    for (const [name, test] of Object.entries(tests)) {
-      console.log(`  - ${display(name)}...`);
-      const testResults: PerfResults[] = [];
-      suiteResults[name] = testResults;
-
-      if (test.getVisibleEnabledPositions) {
-        if (test.type === "create") {
-          throw new Error("Cannot have getVisibleEnabledPositions with create test");
-        }
-        //  we will run a small n sample of this to verify it works correctly.
-        const sample_n = 17;
-        await test.setup(sample_n);
-        const initialPositions = test.getVisibleEnabledPositions();
-        const expectedInitialPositions = [1, 1, 1, 5, 5, 5, 9, 9, 9, 13, 13, 13, 17, 17, 17];
-        if (JSON.stringify(initialPositions) !== JSON.stringify(expectedInitialPositions)) {
-          console.log(`  Error: invalid initial positions: ${initialPositions}, expected. ${expectedInitialPositions}`);
-        }
-        // console.log(JSON.stringify(initialPositions));
-        //  run the test once to add to visible, enabled particle positions.
-        test.run();
-        const finalPositions = test.getVisibleEnabledPositions();
-        const expectedFinalPositions = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1];
-        if (JSON.stringify(finalPositions) !== JSON.stringify(expectedFinalPositions)) {
-          console.log(`  Error: invalid final positions: ${finalPositions}, expected. ${expectedFinalPositions}`);
-        }
-        // console.log(JSON.stringify(finalPositions));
-      }
-
-      const n = test.getVisibleEnabledPositions ? 100_000 : 100_000;
-
-      await test.setup(n);
-      garbageCollect();
-
-      const baselineMemory = getMemory();
-      const timeStart = getTime();
-
-      //   only run for 1 second
-      while (getTime() - timeStart < 100) {
-        const result = runOnce(test.run, test);
-        result.memoryKb -= baselineMemory;
-        testResults.push({...result, flops: n * typeToFlops[test.type] });
-      }
-
-      await test.cleanup();
-      garbageCollect();
-    }
-  }
-  // console.log(allResults);
-  //  console log some meaningful and readable results for each test that include the min, max and average times
-  if (typeof console.table === "function") {
-    // Let's use the console table function to layout some nice results that the best results in time and memory
-    // are easy to see.
-    const tableValues = {} as any;
-    for (const [suite, suiteResults] of Object.entries(allResults)) {
-      for (const [name, testResults] of Object.entries(suiteResults)) {
-        const memoryKb = testResults.map((r) => r.memoryKb / (1024 * 1024));
-        const timeMs = testResults.map((r) => r.timeMs);
-        const fastestResult = testResults.reduce(
-          (a, b) => (a.timeMs < b.timeMs ? a : b)
-        );
-        const fastestFlopsPerSecond = (fastestResult.flops * 1000) / (fastestResult.timeMs);
-        const totalTime = timeMs.reduce((a, b) => a + b, 0);
-        const totalFlops = testResults.reduce((a, b) => a + b.flops, 0);
-        const averageFlopsPerSecond = (totalFlops * 1000) / totalTime;
-        tableValues[`${display(suite)}:${display(name)}`] = {
-          Passes: memoryKb.length,
-          // 'Mem Min (Mb)': Math.min(...memoryKb).toFixed(2),
-          // 'Mem Max (Mb)': Math.max(...memoryKb).toFixed(2),
-          // "Mem Avg (Mb)": (
-          //   memoryKb.reduce((a, b) => a + b, 0) / memoryKb.length
-          // ).toFixed(2),
-          "Time Min (ms)": Math.min(...timeMs).toFixed(2),
-          // 'Time Max (ms)': Math.max(...timeMs).toFixed(2),
-          "Time Avg (ms)": (
-            timeMs.reduce((a, b) => a + b, 0) / timeMs.length
-          ).toFixed(2),
-          "Fastest MFlops": Math.round(fastestFlopsPerSecond / 1_000_000),
-          "Average MFlops": Math.round(averageFlopsPerSecond / 1_000_000),
-        };
-      }
-    }
-    console.table(tableValues);
-  } else {
-    for (const [suite, suiteResults] of Object.entries(allResults)) {
-      for (const [name, testResults] of Object.entries(suiteResults)) {
-        const memoryKb = testResults.map((r) => r.memoryKb);
-        const timeMs = testResults.map((r) => r.timeMs);
-        console.log(
-          `${name}: ${Math.min(...memoryKb)}kb - ${Math.max(...memoryKb)}kb - ${Math.round(memoryKb.reduce((a, b) => a + b, 0) / memoryKb.length)}kb`
-        );
-        console.log(
-          `${name}: ${Math.round(Math.min(...timeMs))}ms - ${Math.round(Math.max(...timeMs))}ms - ${Math.round(timeMs.reduce((a, b) => a + b, 0) / timeMs.length)}ms`
-        );
-      }
-    }
-  }
-}
-
-function runOnce(fn: () => any, test: PerformanceTest): Omit<PerfResults, "flops"> {
-  const start = getTime();
-  const result = fn();
-  const end = getTime();
-  const after = getMemory();
-  const timeMs = end - start;
-  return { memoryKb: after, timeMs, result };
-}

package/src/perftest/perf.md

@@ -1,90 +0,0 @@
-
-# Performance Findings
-
-## Tests
-
-- Create 1 million particles
-    - Particles have
-        - color: u32
-        - mass: f32
-        - position: f32
-        - velocity: f32
-        - visible?: true
-        - enabled?: true
-    - 50Mb Expected memory size assuming 16 byte overhead per Particle
-    - 1/4 of particles enabled and visible
-    - 1/4 of particles enabled
-    - 1/4 of particles visible
-    - 1/4 of particles neither
-- Process All visible and enabled particles
-    - add velocity to position for each
-    - test with freshly allocated linear memory (best) and shuffled (worst)
-
-## Techniques Tested
-
-- Plain old Javascript Objects (POJO)
-- Immutable Javascript Objects (IJO)
-- Mobx Observable Javascript Objects (MOBX)
-- Horizon Emulated Storage (HORIZON*)
-- Entity Component System (ECS)
-
-## Results
-
-              Create      Create      Process     Process     Notes
-              Memory      Time        Best        Worst
-
-    POJO      248 mb       124 ms     145 ms      363 ms
-    POJO M1   248 mb        62 ms      58 ms      302 ms      memory is way more efficient on M1
-    IJO       248 mb       124 ms     656 ms      844 ms      much memory allocation on process 
-    MOBX      994 mb      1600 ms     160 ms      437 ms      some memory allocation on process *
-    HORIZON*  991 mb      1650 ms    1214 ms     2415 ms      much memory allocation on process
-    ECS        59 mb       410 ms      15 ms       15 ms
-    ECS M1     59 mb       410 ms      10 ms       10 ms      memory was already efficient before
-    ECS M1 WASM            410 ms       4 ms        4 ms      compiler simd ops #add_arrays
-    ECS M1 WASM SIMD       410 ms       3 ms        3 ms      manual simd ops #add_arrays_simd
-
-    RUST OPTIMIZED COMMAND LINE      0.15 ms     0.15 ms      raw processing of minimum memory
-    THEORETICAL M1 MAX               0.12 ms     0.12 ms      single core execution, no gpu
-
-## Findings / Reasons
-
-- Plain Javascript Objects are the fastest to create.
-    - highly optimized in V8
-- Immutable Javascript Objects are the slowest to process.
-    - new allocation slower than mutate in place
-- Mobx is the slowest to create by an order of magnitude.
-    - likely due to Proxy creation
-- Mobx uses the most memory by a factor of 20.
-    - likely due to Proxy creation
-- Horizon* was emulated using UUIDV4 and Map of Maps with immutable components.
-    - This is consistent with very best possible case horizon performance.
-    - Horizon ECS does allow us to only process the 1/4 that are visible + enabled.
-- ECS is the most efficient in memory by a factor of 5
-    - ECS is storing in f32 and others storing large numbers in f64
-    - ECS is not allocating per entity for enabled/visible flags.
-- ECS is the most efficient in processing by a factor of 10
-    - All enabled/visible particle components are allocated adjacently for optimal cache behavior
-- M1 chip seems to have three times faster memory bandwidth, tripling best case speed.
-- M1 chip cache misses are still expensive which is likely why worst case only a bit better.
-- Rust to Wasm compiler can automatically insert SIMD instructions.
-- Explicit SIMD instructions are a bit faster.
-- Maximum theoretical performance from optimized rust command line is about 20 times faster than our best.
-
-
-## Summary
-
-- ECS trades extra time at creation for significant improvements to memory usage and processing performance.
-
-## Notes
-
-- Plain javascript object memory size per property depends upon number value used. For small integers, it seems a 32 bit format is used, but for larger floating point values a 64 bit is used.
-- If you run the tests with only small integer values then the memory results are almost half the size.
-- Prompt to ask Chat GPT 4 maximum theoretical performance:
-
-    theoretical performance question. How fast should a Macbook Pro M1 2021 be able to perform the following processing:
-
-    given 12MB of f32 array data split into two arrays. How fast can it add each float to the corresponding float in the second array and write the result to the second array?
-- Answer
-    Assuming only one core is used, the theoretical peak performance for this simple operation could be 3 GHz * 8 floats/cycle = 24 billion floats/second.
-
-    or 0.125 ms

package/src/perftest/vanilla-perf.ts

@@ -1,136 +0,0 @@
-/*MIT License
-
-© Copyright 2025 Adobe. All rights reserved.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.*/
-import { shuffleArray } from "./helper-functions.js";
-import { PerformanceTest } from "./perf-test.js";
-
-function createParticlesJS(n: number) {
-  const particles: any[] = [];
-  for (let i = 0; i < n; i++) {
-    const particle: any = {
-      color: 0xff00ff,
-      mass: 10,
-      positionX: i + 1,
-      positionY: i + 1,
-      positionZ: i + 1,
-      velocityX: -i,
-      velocityY: -i,
-      velocityZ: -i,
-    };
-    if ((i >> 0) % 2 === 0) {
-      particle.visible = true;
-    }
-    if ((i >> 1) % 2 === 0) {
-      particle.enabled = true;
-    }
-    particles.push(particle);
-  }
-  return particles;
-}
-
-const create = (() => {
-  let count = 0;
-  const setup = async (n: number) => {
-    count = n;
-  };
-  const run = () => {
-    createParticlesJS(count);
-  };
-  const cleanup = async () => {};
-  return { setup, run: run, cleanup, type: "create" } satisfies PerformanceTest;
-})();
-
-function createMoveParticlesPerformanceTest(options: {
-  shuffle: boolean;
-  immutable: boolean;
-}) {
-  let particles: any[] = [];
-  const setup = async (n: number) => {
-    particles = createParticlesJS(n);
-    if (options.shuffle) {
-      shuffleArray(particles);
-    }
-  };
-  const run = () => {
-    if (options.immutable) {
-      for (let i = 0; i < particles.length; i++) {
-        const p = particles[i];
-        if (p.visible && p.enabled) {
-          particles[i] = {
-            ...p,
-            positionX: p.positionX + p.velocityX,
-            positionY: p.positionY + p.velocityY,
-            positionZ: p.positionZ + p.velocityZ,
-          };
-        }
-      }
-    } else {
-      for (let i = 0; i < particles.length; i++) {
-        const p = particles[i];
-        if (p.visible && p.enabled) {
-          p.positionX += p.velocityX;
-          p.positionY += p.velocityY;
-          p.positionZ += p.velocityZ;
-        }
-      }
-    }
-  };
-  const getVisibleEnabledPositions = () => {
-    const values: number[] = [];
-    for (let i = 0; i < particles.length; i++) {
-      const p = particles[i];
-      if (p.visible && p.enabled) {
-        values.push(p.positionX, p.positionY, p.positionZ);
-      }
-    }
-    return values;
-  }
-  const cleanup = async () => {};
-  return { setup, run: run, cleanup, getVisibleEnabledPositions: options.shuffle ? undefined : getVisibleEnabledPositions, type: "move" } satisfies PerformanceTest;
-}
-
-const move_best = createMoveParticlesPerformanceTest({
-  shuffle: false,
-  immutable: false,
-});
-const move_worst = createMoveParticlesPerformanceTest({
-  shuffle: true,
-  immutable: false,
-});
-const move_best_immutable = createMoveParticlesPerformanceTest({
-  shuffle: false,
-  immutable: true,
-});
-const move_worst_immutable = createMoveParticlesPerformanceTest({
-  shuffle: true,
-  immutable: true,
-});
-
-export const vanilla_js = {
-  create,
-  move_best,
-  move_worst,
-};
-
-export const immutable_js = {
-  move_best: move_best_immutable,
-  move_worst: move_worst_immutable,
-};

package/src/schema/boolean.ts

@@ -1,5 +0,0 @@
-import { Schema } from "@cfworker/json-schema";
-
-export const BooleanSchema = {
-    type: 'boolean',
-} as const satisfies Schema;

package/src/schema/dynamic/deep-merge.test.ts

@@ -1,100 +0,0 @@
-/*MIT License
-
-© Copyright 2025 Adobe. All rights reserved.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.*/
-import { deepMerge } from './deep-merge.js';
-import { assert } from 'riteway/vitest';
-import { describe, test } from 'vitest';
-
-describe('deepMerge', () => {
-  test('should merge two objects', () => {
-    const a = { a: 1, b: 2 };
-    const b = { c: 3, d: 4 };
-    assert({
-      given: 'two objects without overlapping keys',
-      should: 'merge them',
-      actual: deepMerge(a, b),
-      expected: { a: 1, b: 2, c: 3, d: 4 },
-    });
-  });
-
-  test('should merge two objects with overlapping keys', () => {
-    const a = { a: 1, b: 2 };
-    const b = { b: 3, c: 4 };
-    assert({
-      given: 'two objects with overlapping keys',
-      should: 'merge them',
-      actual: deepMerge(a, b),
-      expected: { a: 1, b: 3, c: 4 },
-    });
-  });
-
-  test('should merge two objects with overlapping keys and arrays', () => {
-    const a = { a: 1, b: [1, 2] };
-    const b = { b: [3, 4], c: 4 };
-    assert({
-      given: 'two objects with overlapping keys and arrays',
-      should: 'merge them',
-      actual: deepMerge(a, b),
-      expected: { a: 1, b: [1, 2, 3, 4], c: 4 },
-    });
-  });
-
-  test('should merge two nested objects with overlapping keys', () => {
-    const a = { a: 1, b: { c: 2, d: 3 } };
-    const b = { b: { d: 4, e: 5 }, c: 6 };
-    assert({
-      given: 'two nested objects with overlapping keys',
-      should: 'merge them',
-      actual: deepMerge(a, b),
-      expected: { a: 1, b: { c: 2, d: 4, e: 5 }, c: 6 },
-    });
-  });
-
-  test('should merge two objects with null values', () => {
-    const a = { a: null, b: 2 };
-    const b = { b: null, c: 4 };
-    assert({
-      given: 'two objects with null values',
-      should: 'merge them',
-      actual: deepMerge(a, b),
-      expected: { a: null, b: null, c: 4 },
-    });
-  });
-
-  test('should merge two objects with undefined values', () => {
-    const a = { a: undefined, b: 2 };
-    const b = { b: undefined, c: 4 };
-    assert({
-      given: 'two objects with undefined values',
-      should: 'merge them',
-      actual: deepMerge(a, b),
-      expected: { a: undefined, b: undefined, c: 4 },
-    });
-  });
-
-  test('should not mutate the original objects', () => {
-    const a = { a: 1, b: 2 };
-    const b = { b: 3, c: 4 };
-    deepMerge(a, b);
-    assert({ given: 'the original objects', should: 'not be mutated', actual: a, expected: { a: 1, b: 2 } });
-    assert({ given: 'the original objects', should: 'not be mutated', actual: b, expected: { b: 3, c: 4 } });
-  });
-});

package/src/schema/dynamic/deep-merge.ts

@@ -1,67 +0,0 @@
-/*MIT License
-
-© Copyright 2025 Adobe. All rights reserved.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.*/
-import { type Data } from '../../index.js';
-
-/**
- * Recursively merges 2 pieces of `Data`, returns new `Data`.
- * Inputs are not mutated.
- * 
- * @param {Data} a First piece of `Data`.
- * @param {Data} b The second piece of `Data`.
- * @returns {Object} Returns new `Data`.
- * @example
- *
- * const one = {
- *   'a': [{ 'b': 2 }, { 'd': 4 }]
- * };
- *
- * const other = {
- *   'a': [{ 'c': 3 }, { 'e': 5 }]
- * };
- *
- * deepMerge(one, other);
- * // => { 'a': [{ 'b': 2, 'c': 3 }, { 'd': 4, 'e': 5 }] }
- */
-export const deepMerge = <A, B>(a: A, b: B, options: { mergeArrays?: boolean } = {}): A & B => {
-  const { mergeArrays = true } = options;
-  // Handle null/undefined cases
-  if (a == null || typeof a !== 'object' || typeof b !== 'object') return b as A & B;
-
-  // Handle arrays
-  if (Array.isArray(a) && Array.isArray(b)) {
-    if (mergeArrays) {
-      return [...a, ...b] as unknown as A & B;
-    } else {
-      return b as A & B;
-    }
-  }
-
-  // Handle objects
-  const result = { ...a } as Record<string, Data>;
-  for (const key in b) {
-    if (Object.prototype.hasOwnProperty.call(b, key)) {
-      const value = (b as Record<string, Data>)[key];
-      result[key] = deepMerge((a as Record<string, Data>)[key], value, options);
-    }
-  }
-  return result as A & B;
-};