lentil/rhizome-node
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: lentil:d7c4fda93e0e46a12d8140a94ccedfb6c2c7d6df
Branches Tags
lentil:main
..
compare: lentil:ef6efe758f7f2e075a3722c81fe997894342c5a1
Branches Tags
lentil:main

No commits in common. "d7c4fda93e0e46a12d8140a94ccedfb6c2c7d6df" and "ef6efe758f7f2e075a3722c81fe997894342c5a1" have entirely different histories.
d7c4fda93e ... ef6efe758f

95 changed files with 1987 additions and 4041 deletions
Show Stats Expand all files Collapse all files

2
.gitignore vendored
View File

@ -7,4 +7,4 @@ coverage/
data/
test-data/
*.code-workspace
__notes__/
local-notes/

5
README.md
View File

@ -1,10 +1,5 @@
See [spec.md](spec.md) for additional specification details about this project.
## Documentation
- [Custom Resolvers](./docs/custom-resolvers/overview.md) - Flexible property resolution system with plugin support
# Development / Demo
## Setup

11
__plans__/housekeeping.md
View File

@ -1,11 +0,0 @@
# Housekeeping tasks
- [x] Organize tests?
- [x] More documentation in docs/
- [ ] Rename/consolidate, lossless view() and compose() --> composeView()
- [ ] Rename Lossless to HyperView
- [ ] Rename Lossy to View
- [ ] Consider whether we should use collapsed deltas
- [ ] Improve ergonomics of declaring multiple entity properties in one delta
- [x] Use dotenv so we can more easily manage the local dev test environment
- [ ] Create test helpers to reduce boilerplate

13
__plans__/test-helpers.md
View File

@ -1,13 +0,0 @@
# Test structure
- before test, initialize node and lossless view
- when test begins, create and ingest a series of deltas
- instantiate a resolver, in this case using custom resolver plugins
- call the resolver's initializer with the view
- call the resolver's reducer with the view
- call the resolver's resolver with the view
- expect the resolver to return the expected result
# Follow-up
- why isn't the resolver being called automatically, by event dispatch?
- we can prepare an array of deltas and pass it to a test helper,
- So our entire test case should consist of the deltas, the resolver, and the expected result.

52
__tests__/__helpers__/resolver-test-helper.ts
View File

@ -1,52 +0,0 @@
import { RhizomeNode } from '@src';
import { Lossless } from '@src/views/lossless';
import { Delta } from '@src/core/delta';
import { createDelta } from '@src/core/delta-builder';
import { CustomResolver } from '@src/views/resolvers/custom-resolvers';
import { ResolverPlugin } from '@src/views/resolvers/custom-resolvers/plugin';
// Define a test plugin map that enforces string dependencies
type TestPluginMap = {
[key: string]: ResolverPlugin<unknown, string>;
};
interface TestHelperOptions<T extends TestPluginMap> {
entityId?: string;
plugins: T;
deltas: Delta[];
}
export async function testResolverWithPlugins<T extends TestPluginMap>(
options: TestHelperOptions<T>
) {
const {
entityId = 'test-entity',
plugins,
deltas,
} = options;
// Setup test environment
const node = new RhizomeNode();
const lossless = new Lossless(node);
const view = new CustomResolver(lossless, plugins);
// Ingest all deltas through the lossless instance
for (const delta of deltas) {
lossless.ingestDelta(delta);
}
// Get the resolved view
const resolvedView = view.resolve([entityId]);
if (!resolvedView) throw new Error(`Resolved view for entity ${entityId} is undefined`);
return resolvedView[entityId];
}
/**
* Helper to create a test delta with proper typing
* @param creator The creator of the delta
* @param host The host of the delta
* @returns A test delta
*/
export function createTestDelta(creator = 'user1', host = 'host1') {
return createDelta(creator, host);
}

6
__tests__/e2e/001-single-node-orchestrated.test.ts
View File

@ -1,5 +1,5 @@
import { createOrchestrator, type NodeConfig } from '@src/orchestration';
import type { NodeHandle } from '@src/orchestration/types';
import { createOrchestrator, type NodeConfig } from '../../src/orchestration';
import type { NodeHandle } from '../../src/orchestration/types';
// Increase test timeout to 30 seconds
jest.setTimeout(30000);
@ -24,7 +24,7 @@ describe('Run (Orchestrated)', () => {
}
});
test('can put a new user and fetch it', async () => {
it('can put a new user and fetch it', async () => {
// Create a new record
const createResponse = await fetch(`${apiUrl}/user`, {
method: 'PUT',

2
__tests__/e2e/001-single-node.test.ts
View File

@ -18,7 +18,7 @@ describe('Run', () => {
await app.stop();
});
test('can put a new user and fetch it', async () => {
it('can put a new user and fetch it', async () => {
// Create a new record
{
const res = await fetch(`${app.apiUrl}/user`, {

8
__tests__/e2e/002-two-nodes-orchestrated.test.ts
View File

@ -1,11 +1,11 @@
import Debug from 'debug';
import { createOrchestrator } from '@src/orchestration';
import type { NodeConfig, NodeHandle } from '@src/orchestration';
import { createOrchestrator } from '../../src/orchestration';
import type { NodeConfig, NodeHandle } from '../../src/orchestration';
// Increase test timeout to 30 seconds
jest.setTimeout(30000);
const debug = Debug('rz:test:two-orchestrated');
const debug = Debug('test:two-orchestrated');
describe('Run (Two Nodes Orchestrated)', () => {
const orchestrator = createOrchestrator('in-memory');
@ -46,7 +46,7 @@ describe('Run (Two Nodes Orchestrated)', () => {
await Promise.all(nodes.map(node => node && orchestrator.stopNode(node)));
});
test('can create a record on node0 and read it from node1', async () => {
it('can create a record on node0 and read it from node1', async () => {
const [node0, node1] = nodes;
const node0Url = node0.getApiUrl();
const node1Url = node1.getApiUrl();

4
__tests__/e2e/002-two-nodes.test.ts
View File

@ -1,6 +1,6 @@
import Debug from 'debug';
import {App} from '../../util/app';
const debug = Debug('rz:test:two');
const debug = Debug('test:two');
describe('Run', () => {
const apps: App[] = [];
@ -24,7 +24,7 @@ describe('Run', () => {
await Promise.all(apps.map((app) => app.stop()));
});
test('can create a record on app0 and read it on app1', async () => {
it('can create a record on app0 and read it on app1', async () => {
debug('apps[0].apiUrl', apps[0].apiUrl);
debug('apps[1].apiUrl', apps[1].apiUrl);

15
__tests__/e2e/005-docker-orchestrator.test.ts
View File

@ -1,10 +1,9 @@
import Docker from 'dockerode';
import { describe, it, beforeAll, afterAll, expect, jest } from '@jest/globals';
import type { NodeConfig, NodeHandle, NodeStatus } from '@src/orchestration';
import { DockerOrchestrator, createOrchestrator } from '@src/orchestration';
import { ImageManager } from '@src/orchestration/docker-orchestrator/managers/image-manager';
import type { NodeConfig, NodeHandle, NodeStatus } from '../../src/orchestration';
import { DockerOrchestrator, createOrchestrator } from '../../src/orchestration';
import { ImageManager } from '../../src/orchestration/docker-orchestrator/managers/image-manager';
import Debug from 'debug';
import { DOCKER_ENABLE } from '@src/config';
const debug = Debug('rz:test:docker-orchestrator-v2');
@ -26,7 +25,7 @@ interface ExtendedNodeStatus extends Omit<NodeStatus, 'network'> {
// Set default timeout for all tests to 5 minutes
jest.setTimeout(300000);
(DOCKER_ENABLE ? describe : describe.skip)('Docker Orchestrator', () => {
describe('Docker Orchestrator', () => {
let docker: Docker;
let orchestrator: DockerOrchestrator;
let nodeConfig: NodeConfig;
@ -87,7 +86,7 @@ jest.setTimeout(300000);
/**
* ! Note that this test fails if the build fails
*/
test('should start and stop a node', async () => {
it('should start and stop a node', async () => {
debug('Starting test: should start and stop a node');
// Create a new config with a unique ID for this test
@ -143,7 +142,7 @@ jest.setTimeout(300000);
}
});
test('should enforce resource limits', async () => {
it('should enforce resource limits', async () => {
debug('Starting test: should enforce resource limits');
// Create a new node with a unique ID for this test
@ -227,7 +226,7 @@ jest.setTimeout(300000);
}
}, 30000);
test('should expose API endpoints', async () => {
it('should expose API endpoints', async () => {
// Set a longer timeout for this test (5 minutes)
jest.setTimeout(300000);
debug('Starting test: should expose API endpoints');

50
__tests__/integration/schema.test.ts
View File

@ -1,16 +1,16 @@
import { LosslessViewOne } from '@src/views/lossless';
import { LosslessViewOne } from '../../src/views/lossless';
import {
SchemaBuilder,
PrimitiveSchemas,
ReferenceSchemas,
ArraySchemas,
ObjectSchema
} from '@src/schema';
import { DefaultSchemaRegistry } from '@src/schema';
} from '../../src/schema';
import { DefaultSchemaRegistry } from '../../src/schema';
import { CommonSchemas } from '../../util/schemas';
import { TypedCollectionImpl, SchemaValidationError } from '@src/collections';
import { RhizomeNode } from '@src/node';
import { createDelta } from '@src/core/delta-builder';
import { TypedCollectionImpl, SchemaValidationError } from '../../src/collections';
import { RhizomeNode } from '../../src/node';
import { createDelta } from '../../src/core/delta-builder';
describe('Schema System', () => {
let schemaRegistry: DefaultSchemaRegistry;
@ -24,7 +24,7 @@ describe('Schema System', () => {
describe('Schema Builder', () => {
test('should create a basic schema', () => {
it('should create a basic schema', () => {
const schema = SchemaBuilder
.create('user')
.name('User')
@ -46,7 +46,7 @@ describe('Schema System', () => {
expect(schema.requiredProperties).toContain('name');
});
test('should create schema with references', () => {
it('should create schema with references', () => {
const schema = SchemaBuilder
.create('post')
.name('Post')
@ -67,7 +67,7 @@ describe('Schema System', () => {
});
});
test('should enforce required fields', () => {
it('should enforce required fields', () => {
expect(() => {
SchemaBuilder.create('').build();
}).toThrow('Schema must have id and name');
@ -79,7 +79,7 @@ describe('Schema System', () => {
});
describe('Schema Registry', () => {
test('should register and retrieve schemas', () => {
it('should register and retrieve schemas', () => {
const schema = CommonSchemas.User();
schemaRegistry.register(schema);
@ -90,7 +90,7 @@ describe('Schema System', () => {
expect(all).toContain(schema);
});
test('should validate schema structure', () => {
it('should validate schema structure', () => {
const invalidSchema = {
id: 'invalid',
name: 'Invalid',
@ -104,7 +104,7 @@ describe('Schema System', () => {
}).toThrow('Unknown schema type');
});
test('should validate required properties exist', () => {
it('should validate required properties exist', () => {
const schema = SchemaBuilder
.create('test')
.name('Test')
@ -117,7 +117,7 @@ describe('Schema System', () => {
}).toThrow("Required property 'nonexistent' not found");
});
test('should detect circular dependencies', () => {
it('should detect circular dependencies', () => {
// Create schemas with circular references
const userSchema = SchemaBuilder
.create('user')
@ -151,7 +151,7 @@ describe('Schema System', () => {
expect(schemaRegistry.hasCircularDependencies()).toBe(true);
});
test('should validate lossless views against schemas', () => {
it('should validate lossless views against schemas', () => {
const userSchema = CommonSchemas.User();
schemaRegistry.register(userSchema);
@ -206,7 +206,7 @@ describe('Schema System', () => {
);
});
test('should validate primitive types', () => {
it('should validate primitive types', () => {
const schema = SchemaBuilder
.create('test')
.name('Test')
@ -248,7 +248,7 @@ describe('Schema System', () => {
});
describe('Typed Collection', () => {
test('should create typed collection with schema validation', () => {
it('should create typed collection with schema validation', () => {
const userSchema = CommonSchemas.User();
const collection = new TypedCollectionImpl<{
name: string;
@ -261,7 +261,7 @@ describe('Schema System', () => {
expect(collection.name).toBe('users');
});
test('should validate entities against schema', () => {
it('should validate entities against schema', () => {
const userSchema = CommonSchemas.User();
const collection = new TypedCollectionImpl<{
name: string;
@ -280,7 +280,7 @@ describe('Schema System', () => {
expect(invalidResult.valid).toBe(false);
});
test('should enforce strict validation on put operations', async () => {
it('should enforce strict validation on put operations', async () => {
const userSchema = CommonSchemas.User();
const collection = new TypedCollectionImpl<{
name: string;
@ -296,7 +296,7 @@ describe('Schema System', () => {
await expect(collection.put('user2', { email: 'invalid@test.com' })).rejects.toThrow(SchemaValidationError);
});
test('should provide validation statistics', async () => {
it('should provide validation statistics', async () => {
const userSchema = CommonSchemas.User();
const collection = new TypedCollectionImpl<{
name: string;
@ -322,7 +322,7 @@ describe('Schema System', () => {
expect(stats.invalidEntities).toBe(1);
});
test('should filter valid and invalid entities', async () => {
it('should filter valid and invalid entities', async () => {
const userSchema = CommonSchemas.User();
const collection = new TypedCollectionImpl<{
name: string;
@ -351,7 +351,7 @@ describe('Schema System', () => {
expect(invalidEntities[0].entityId).toBe('user3');
});
test('should apply schema to lossless views', async () => {
it('should apply schema to lossless views', async () => {
const userSchema = CommonSchemas.User();
const collection = new TypedCollectionImpl<{
name: string;
@ -370,7 +370,7 @@ describe('Schema System', () => {
expect(validatedView!.metadata?.appliedAt).toBeDefined();
});
test('should provide schema introspection', () => {
it('should provide schema introspection', () => {
const userSchema = CommonSchemas.User();
schemaRegistry.register(CommonSchemas.UserSummary());
@ -386,7 +386,7 @@ describe('Schema System', () => {
});
describe('Common Schemas', () => {
test('should provide working User schema', () => {
it('should provide working User schema', () => {
const userSchema = CommonSchemas.User();
expect(userSchema.id).toBe('user');
expect(userSchema.name).toBe('User');
@ -395,7 +395,7 @@ describe('Schema System', () => {
expect(userSchema.requiredProperties).toContain('name');
});
test('should provide working Document schema', () => {
it('should provide working Document schema', () => {
const docSchema = CommonSchemas.Document();
expect(docSchema.id).toBe('document');
expect(docSchema.properties.title).toBeDefined();
@ -404,7 +404,7 @@ describe('Schema System', () => {
expect(docSchema.requiredProperties).toContain('author');
});
test('should work together in a registry', () => {
it('should work together in a registry', () => {
schemaRegistry.register(CommonSchemas.User());
schemaRegistry.register(CommonSchemas.UserSummary());
schemaRegistry.register(CommonSchemas.Document());

30
__tests__/integration/storage.test.ts
View File

@ -1,6 +1,6 @@
import { MemoryDeltaStorage, LevelDBDeltaStorage, StorageFactory } from '@src/storage';
import { createDelta } from '@src/core/delta-builder';
import { DeltaQueryStorage } from '@src/storage/interface';
import { MemoryDeltaStorage, LevelDBDeltaStorage, StorageFactory } from '../../src/storage';
import { createDelta } from '../../src/core/delta-builder';
import { DeltaQueryStorage } from '../../src/storage/interface';
describe('Delta Storage', () => {
const testDeltas = [
@ -52,12 +52,12 @@ describe('Delta Storage', () => {
});
describe('Storage Factory', () => {
test('creates memory storage', () => {
it('creates memory storage', () => {
const storage = StorageFactory.create({ type: 'memory' });
expect(storage).toBeInstanceOf(MemoryDeltaStorage);
});
test('creates LevelDB storage', () => {
it('creates LevelDB storage', () => {
const storage = StorageFactory.create({
type: 'leveldb',
path: './test-data/factory-test'
@ -65,7 +65,7 @@ describe('Delta Storage', () => {
expect(storage).toBeInstanceOf(LevelDBDeltaStorage);
});
test('throws on unknown storage type', () => {
it('throws on unknown storage type', () => {
expect(() => {
StorageFactory.create({ type: 'unknown' as 'memory' | 'leveldb' });
}).toThrow('Unknown storage type: unknown');
@ -73,7 +73,7 @@ describe('Delta Storage', () => {
});
function runStorageTests(getStorage: () => DeltaQueryStorage) {
test('stores and retrieves deltas', async () => {
it('stores and retrieves deltas', async () => {
const storage = getStorage();
// Store deltas
@ -92,7 +92,7 @@ describe('Delta Storage', () => {
expect(nonExistent).toBeNull();
});
test('gets all deltas', async () => {
it('gets all deltas', async () => {
const storage = getStorage();
for (const delta of testDeltas) {
@ -108,7 +108,7 @@ describe('Delta Storage', () => {
expect(deltaIds).toContain('delta3');
});
test('filters deltas', async () => {
it('filters deltas', async () => {
const storage = getStorage();
for (const delta of testDeltas) {
@ -121,7 +121,7 @@ describe('Delta Storage', () => {
expect(aliceDeltas.every(d => d.creator === 'alice')).toBe(true);
});
test('gets deltas for entity', async () => {
it('gets deltas for entity', async () => {
const storage = getStorage();
for (const delta of testDeltas) {
@ -138,7 +138,7 @@ describe('Delta Storage', () => {
expect(nonExistentDeltas).toHaveLength(0);
});
test('gets deltas by context', async () => {
it('gets deltas by context', async () => {
const storage = getStorage();
for (const delta of testDeltas) {
@ -157,7 +157,7 @@ describe('Delta Storage', () => {
expect(nonExistentDeltas).toHaveLength(0);
});
test('queries deltas with complex criteria', async () => {
it('queries deltas with complex criteria', async () => {
const storage = getStorage();
for (const delta of testDeltas) {
@ -189,7 +189,7 @@ describe('Delta Storage', () => {
expect(aliceUser1Deltas[0].id).toBe('delta1');
});
test('applies pagination to queries', async () => {
it('applies pagination to queries', async () => {
const storage = getStorage();
for (const delta of testDeltas) {
@ -209,7 +209,7 @@ describe('Delta Storage', () => {
expect(pagedDeltas).toHaveLength(1);
});
test('counts deltas', async () => {
it('counts deltas', async () => {
const storage = getStorage();
for (const delta of testDeltas) {
@ -226,7 +226,7 @@ describe('Delta Storage', () => {
expect(user1Count).toBe(2);
});
test('provides storage statistics', async () => {
it('provides storage statistics', async () => {
const storage = getStorage();
for (const delta of testDeltas) {

2
__tests__/jest-setup.ts
View File

@ -1,2 +0,0 @@
import dotenv from 'dotenv';
dotenv.config();

2
__tests__/performance/concurrent-writes.test.ts
View File

@ -1,4 +1,4 @@
import { createDelta } from '@src/core/delta-builder';
import { createDelta } from '../../src/core/delta-builder';
import {
RhizomeNode,
Lossless,

22
__tests__/performance/nested-resolution-performance.test.ts
View File

@ -9,11 +9,11 @@
*/
import Debug from 'debug';
import { RhizomeNode } from '@src/node';
import { createDelta } from '@src/core';
import { DefaultSchemaRegistry } from '@src/schema';
import { SchemaBuilder, PrimitiveSchemas, ReferenceSchemas, ArraySchemas } from '@src/schema';
import { TypedCollectionImpl } from '@src/collections';
import { RhizomeNode } from '../../src/node';
import { createDelta } from '../../src/core';
import { DefaultSchemaRegistry } from '../../src/schema';
import { SchemaBuilder, PrimitiveSchemas, ReferenceSchemas, ArraySchemas } from '../../src/schema';
import { TypedCollectionImpl } from '../../src/collections';
const debug = Debug('rz:test:nested-resolution-performance');
@ -27,7 +27,7 @@ describe('Nested Object Resolution Performance', () => {
});
describe('Large Network Performance', () => {
test('should handle large networks of interconnected users efficiently', async () => {
it('should handle large networks of interconnected users efficiently', async () => {
// Create a schema for users with multiple relationship types
const networkUserSchema = SchemaBuilder
.create('network-user')
@ -116,7 +116,7 @@ describe('Nested Object Resolution Performance', () => {
// Test resolution performance for a user with many connections
const testUserId = userIds[50]; // Pick a user in the middle
const userViews = node.lossless.compose([testUserId]);
const userViews = node.lossless.view([testUserId]);
const userView = userViews[testUserId];
const startResolution = performance.now();
@ -149,7 +149,7 @@ describe('Nested Object Resolution Performance', () => {
expect(Object.keys(nestedView.nestedObjects).length).toBeGreaterThan(0);
});
test('should handle deep nesting chains efficiently', async () => {
it('should handle deep nesting chains efficiently', async () => {
// Create a simple schema for chain testing
const chainUserSchema = SchemaBuilder
.create('chain-user')
@ -205,7 +205,7 @@ describe('Nested Object Resolution Performance', () => {
// Test resolution from the start of the chain
const firstUserId = userIds[0];
const userViews = node.lossless.compose([firstUserId]);
const userViews = node.lossless.view([firstUserId]);
const userView = userViews[firstUserId];
const startResolution = performance.now();
@ -241,7 +241,7 @@ describe('Nested Object Resolution Performance', () => {
debug(`Actual resolved depth: ${depth}`);
});
test('should handle circular references in large graphs without performance degradation', async () => {
it('should handle circular references in large graphs without performance degradation', async () => {
const circularUserSchema = SchemaBuilder
.create('circular-user')
.name('Circular User')
@ -301,7 +301,7 @@ describe('Nested Object Resolution Performance', () => {
// Test resolution performance with circular references
const testUserId = userIds[0];
const userViews = node.lossless.compose([testUserId]);
const userViews = node.lossless.view([testUserId]);
const userView = userViews[testUserId];
const startResolution = performance.now();

14
__tests__/unit/core/compose-decompose.test.ts
View File

@ -4,8 +4,8 @@
* to the original deltas with all pointer relationships preserved.
*/
import { RhizomeNode } from '@src/node';
import { createDelta } from '@src/core/delta-builder';
import { RhizomeNode } from '../../../src/node';
import { createDelta } from '../../../src/core/delta-builder';
describe('Lossless View Compose/Decompose', () => {
let node: RhizomeNode;
@ -15,7 +15,7 @@ describe('Lossless View Compose/Decompose', () => {
});
describe('Bidirectional Conversion', () => {
test('should compose and decompose simple entity deltas correctly', () => {
it('should compose and decompose simple entity deltas correctly', () => {
// Create simple entity deltas
const nameDeltas = [
createDelta('test-creator', 'test-host')
@ -63,7 +63,7 @@ describe('Lossless View Compose/Decompose', () => {
expect(upPointer?.localContext).toBe('users');
});
test('should handle multi-pointer relationship deltas correctly', () => {
it('should handle multi-pointer relationship deltas correctly', () => {
// Create a complex relationship delta
const relationshipDelta = createDelta('test-creator', 'test-host')
.addPointer('users', 'alice', 'relationships')
@ -101,7 +101,7 @@ describe('Lossless View Compose/Decompose', () => {
expect(intensityPointer?.target).toBe(8);
});
test('should handle reference relationships correctly', () => {
it('should handle reference relationships correctly', () => {
// Create entities first
const aliceDelta = createDelta('test-creator', 'test-host')
.addPointer('users', 'alice', 'name')
@ -146,7 +146,7 @@ describe('Lossless View Compose/Decompose', () => {
expect(bobPointer?.targetContext).toBe('friends');
});
test('should preserve delta metadata correctly', () => {
it('should preserve delta metadata correctly', () => {
const originalDelta = createDelta('test-creator', 'test-host')
.addPointer('users', 'alice', 'name')
.addPointer('name', 'Alice')
@ -167,7 +167,7 @@ describe('Lossless View Compose/Decompose', () => {
expect(reconstituted.timeCreated).toBe(originalDelta.timeCreated);
});
test('should handle multiple deltas for the same property', () => {
it('should handle multiple deltas for the same property', () => {
// Create multiple name changes for alice
const nameDeltas = [
createDelta('test-creator', 'test-host')

38
__tests__/unit/core/delta/delta-builder.test.ts
View File

@ -1,8 +1,8 @@
import { createDelta } from '@src/core/delta-builder';
import { DeltaV1, DeltaV2 } from '@src/core/delta';
import { Lossless } from '@src/views/lossless';
import { RhizomeNode } from '@src/node';
import { TimestampResolver } from '@src/views/resolvers/timestamp-resolvers';
import { createDelta } from '../../../../src/core/delta-builder';
import { DeltaV1, DeltaV2 } from '../../../../src/core/delta';
import { Lossless } from '../../../../src/views/lossless';
import { RhizomeNode } from '../../../../src/node';
import { TimestampResolver } from '../../../../src/views/resolvers/timestamp-resolvers';
describe('DeltaBuilder', () => {
const creator = 'creator-123';
@ -10,7 +10,7 @@ describe('DeltaBuilder', () => {
const node = new RhizomeNode();
describe('V1 Deltas', () => {
test('should create a basic V1 delta', () => {
it('should create a basic V1 delta', () => {
const delta = createDelta(creator, host)
.addPointer('name', 'Test Delta', 'title')
.addPointer('description', 'A test delta', 'description')
@ -28,7 +28,7 @@ describe('DeltaBuilder', () => {
});
});
test('should create a V1 delta with setProperty', () => {
it('should create a V1 delta with setProperty', () => {
const delta = createDelta(creator, host)
.setProperty('entity-1', 'name', 'Test Entity')
.buildV1();
@ -53,7 +53,7 @@ describe('DeltaBuilder', () => {
expect(result!['entity-1'].properties.name).toBe('Test Entity');
});
test('should create a V1 delta with setProperty and entityLabel', () => {
it('should create a V1 delta with setProperty and entityLabel', () => {
const delta = createDelta(creator, host)
.setProperty('entity-1', 'name', 'Test Entity', 'user')
.buildV1();
@ -78,7 +78,7 @@ describe('DeltaBuilder', () => {
expect(result!['entity-1'].properties.name).toBe('Test Entity');
});
test('should create a V1 delta with relationships', () => {
it('should create a V1 delta with relationships', () => {
const delta = createDelta(creator, host)
.relate('user-1', 'user-2', 'follows')
.buildV1();
@ -103,7 +103,7 @@ describe('DeltaBuilder', () => {
});
});
test('should create a V1 delta with relationships and properties', () => {
it('should create a V1 delta with relationships and properties', () => {
const delta = createDelta(creator, host)
.relate('user-1', 'user-2', 'follows', { version: 1})
.buildV1();
@ -134,7 +134,7 @@ describe('DeltaBuilder', () => {
});
describe('V2 Deltas', () => {
test('should create a basic V2 delta', () => {
it('should create a basic V2 delta', () => {
const delta = createDelta(creator, host)
.addPointer('name', 'Test Delta V2', 'title')
.buildV2();
@ -147,7 +147,7 @@ describe('DeltaBuilder', () => {
expect(delta.pointers.name).toEqual({ 'Test Delta V2': 'title' });
});
test('should create a V2 delta with setProperty', () => {
it('should create a V2 delta with setProperty', () => {
const delta = createDelta(creator, host)
.setProperty('entity-1', 'name', 'Test Entity')
.buildV2();
@ -156,7 +156,7 @@ describe('DeltaBuilder', () => {
expect(delta.pointers).toHaveProperty('entity', { 'entity-1': 'name' });
});
test('should create a V2 delta with relationships', () => {
it('should create a V2 delta with relationships', () => {
const delta = createDelta(creator, host)
.relate('user-1', 'user-2', 'follows')
.buildV2();
@ -184,7 +184,7 @@ describe('DeltaBuilder', () => {
});
});
test('should create a V2 delta with relationships and properties', () => {
it('should create a V2 delta with relationships and properties', () => {
const delta = createDelta(creator, host)
.relate('user-1', 'user-2', 'follows', { version: 1})
.buildV2();
@ -217,7 +217,7 @@ describe('DeltaBuilder', () => {
});
describe('Common functionality', () => {
test('should support custom IDs', () => {
it('should support custom IDs', () => {
const customId = 'custom-delta-id';
const delta = createDelta(creator, host)
.withId(customId)
@ -226,7 +226,7 @@ describe('DeltaBuilder', () => {
expect(delta.id).toBe(customId);
});
test('should support transactions', () => {
it('should support transactions', () => {
const txId = 'tx-123';
const delta = createDelta(creator, host)
.inTransaction(txId)
@ -240,7 +240,7 @@ describe('DeltaBuilder', () => {
});
});
test('should support transactions in V2', () => {
it('should support transactions in V2', () => {
const txId = 'tx-123';
const delta = createDelta(creator, host)
.inTransaction(txId)
@ -250,7 +250,7 @@ describe('DeltaBuilder', () => {
expect(delta.pointers['_transaction']).toEqual({ [txId]: 'deltas' });
});
test('should support negation', () => {
it('should support negation', () => {
const negatedId = 'delta-to-negate';
const delta = createDelta(creator, host)
.negate(negatedId)
@ -262,7 +262,7 @@ describe('DeltaBuilder', () => {
expect(negationPointer?.target).toBe(negatedId);
});
test('should support custom timestamps', () => {
it('should support custom timestamps', () => {
const timestamp = Date.now();
const delta = createDelta(creator, host)
.withTimestamp(timestamp)

52
__tests__/unit/core/delta/delta-validation.test.ts
View File

@ -11,14 +11,14 @@ import {
describe("Delta Validation", () => {
describe("Invalid Delta Formats", () => {
describe("DeltaV1 validation", () => {
test("should throw error for non-object delta", () => {
it("should throw error for non-object delta", () => {
expect(() => validateDeltaNetworkImageV1(null)).toThrow(InvalidDeltaFormatError);
expect(() => validateDeltaNetworkImageV1("string")).toThrow(InvalidDeltaFormatError);
expect(() => validateDeltaNetworkImageV1(123)).toThrow(InvalidDeltaFormatError);
expect(() => validateDeltaNetworkImageV1([])).toThrow(InvalidDeltaFormatError);
});
test("should throw error for invalid ID types", () => {
it("should throw error for invalid ID types", () => {
const invalidDeltas = [
{ id: null, timeCreated: 123, host: "host", creator: "creator", pointers: [] },
{ id: 123, timeCreated: 123, host: "host", creator: "creator", pointers: [] },
@ -31,7 +31,7 @@ describe("Delta Validation", () => {
});
});
test("should throw error for invalid timestamp", () => {
it("should throw error for invalid timestamp", () => {
const invalidDeltas = [
{ id: "id", timeCreated: "123", host: "host", creator: "creator", pointers: [] },
{ id: "id", timeCreated: -123, host: "host", creator: "creator", pointers: [] },
@ -44,7 +44,7 @@ describe("Delta Validation", () => {
});
});
test("should throw error for invalid host/creator", () => {
it("should throw error for invalid host/creator", () => {
const invalidDeltas = [
{ id: "id", timeCreated: 123, host: null, creator: "creator", pointers: [] },
{ id: "id", timeCreated: 123, host: "", creator: "creator", pointers: [] },
@ -59,7 +59,7 @@ describe("Delta Validation", () => {
});
});
test("should throw error for non-array pointers", () => {
it("should throw error for non-array pointers", () => {
const invalidDeltas = [
{ id: "id", timeCreated: 123, host: "host", creator: "creator", pointers: null },
{ id: "id", timeCreated: 123, host: "host", creator: "creator", pointers: {} },
@ -72,12 +72,12 @@ describe("Delta Validation", () => {
});
});
test("should throw error for empty pointers array", () => {
it("should throw error for empty pointers array", () => {
const delta = { id: "id", timeCreated: 123, host: "host", creator: "creator", pointers: [] };
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(InvalidDeltaFormatError);
});
test("should throw error for invalid pointer structure", () => {
it("should throw error for invalid pointer structure", () => {
const invalidPointers = [
[null],
["string"],
@ -96,7 +96,7 @@ describe("Delta Validation", () => {
});
});
test("should throw error for invalid targetContext", () => {
it("should throw error for invalid targetContext", () => {
const invalidPointers = [
[{ localContext: "context", target: "target", targetContext: null }],
[{ localContext: "context", target: "target", targetContext: "" }],
@ -110,7 +110,7 @@ describe("Delta Validation", () => {
});
});
test("should throw error for pointer consistency violation", () => {
it("should throw error for pointer consistency violation", () => {
// If targetContext exists, target must be a string (reference)
const pointers = [{ localContext: "context", target: 123, targetContext: "property" }];
const delta = { id: "id", timeCreated: 123, host: "host", creator: "creator", pointers };
@ -119,14 +119,14 @@ describe("Delta Validation", () => {
});
describe("DeltaV2 validation", () => {
test("should throw error for non-object delta", () => {
it("should throw error for non-object delta", () => {
expect(() => validateDeltaNetworkImageV2(null)).toThrow(InvalidDeltaFormatError);
expect(() => validateDeltaNetworkImageV2("string")).toThrow(InvalidDeltaFormatError);
expect(() => validateDeltaNetworkImageV2(123)).toThrow(InvalidDeltaFormatError);
expect(() => validateDeltaNetworkImageV2([])).toThrow(InvalidDeltaFormatError);
});
test("should throw error for invalid pointers object", () => {
it("should throw error for invalid pointers object", () => {
const invalidDeltas = [
{ id: "id", timeCreated: 123, host: "host", creator: "creator", pointers: null },
{ id: "id", timeCreated: 123, host: "host", creator: "creator", pointers: [] },
@ -139,12 +139,12 @@ describe("Delta Validation", () => {
});
});
test("should throw error for empty pointers object", () => {
it("should throw error for empty pointers object", () => {
const delta = { id: "id", timeCreated: 123, host: "host", creator: "creator", pointers: {} };
expect(() => validateDeltaNetworkImageV2(delta)).toThrow(InvalidDeltaFormatError);
});
test("should throw error for invalid pointer keys", () => {
it("should throw error for invalid pointer keys", () => {
const invalidPointers = [
{ "": "value" }
];
@ -155,7 +155,7 @@ describe("Delta Validation", () => {
});
});
test("should throw error for invalid pointer values", () => {
it("should throw error for invalid pointer values", () => {
const invalidPointers = [
{ key: undefined },
{ key: [] }
@ -167,7 +167,7 @@ describe("Delta Validation", () => {
});
});
test("should throw error for invalid reference format", () => {
it("should throw error for invalid reference format", () => {
const invalidReferences = [
{ key: {} }, // Empty reference
{ key: { ref1: "val1", ref2: "val2" } }, // Multiple keys
@ -187,31 +187,31 @@ describe("Delta Validation", () => {
describe("Missing Required Fields", () => {
describe("DeltaV1", () => {
test("should throw MissingRequiredFieldError for missing id", () => {
it("should throw MissingRequiredFieldError for missing id", () => {
const delta = { timeCreated: 123, host: "host", creator: "creator", pointers: [] };
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(MissingRequiredFieldError);
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(/id/);
});
test("should throw MissingRequiredFieldError for missing timeCreated", () => {
it("should throw MissingRequiredFieldError for missing timeCreated", () => {
const delta = { id: "id", host: "host", creator: "creator", pointers: [] };
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(MissingRequiredFieldError);
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(/timeCreated/);
});
test("should throw MissingRequiredFieldError for missing host", () => {
it("should throw MissingRequiredFieldError for missing host", () => {
const delta = { id: "id", timeCreated: 123, creator: "creator", pointers: [] };
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(MissingRequiredFieldError);
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(/host/);
});
test("should throw MissingRequiredFieldError for missing creator", () => {
it("should throw MissingRequiredFieldError for missing creator", () => {
const delta = { id: "id", timeCreated: 123, host: "host", pointers: [] };
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(MissingRequiredFieldError);
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(/creator/);
});
test("should throw MissingRequiredFieldError for missing pointers", () => {
it("should throw MissingRequiredFieldError for missing pointers", () => {
const delta = { id: "id", timeCreated: 123, host: "host", creator: "creator" };
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(MissingRequiredFieldError);
expect(() => validateDeltaNetworkImageV1(delta)).toThrow(/pointers/);
@ -219,7 +219,7 @@ describe("Delta Validation", () => {
});
describe("DeltaV2", () => {
test("should throw MissingRequiredFieldError for all missing fields", () => {
it("should throw MissingRequiredFieldError for all missing fields", () => {
const requiredFields = ["id", "timeCreated", "host", "creator", "pointers"];
requiredFields.forEach(field => {
@ -240,7 +240,7 @@ describe("Delta Validation", () => {
});
describe("Valid Delta Formats", () => {
test("should accept valid DeltaV1", () => {
it("should accept valid DeltaV1", () => {
const validDeltas = [
{
id: "uuid-123",
@ -274,7 +274,7 @@ describe("Delta Validation", () => {
});
});
test("should accept valid DeltaV2", () => {
it("should accept valid DeltaV2", () => {
const validDeltas = [
{
id: "uuid-123",
@ -310,7 +310,7 @@ describe("Delta Validation", () => {
});
describe("Delta class integration", () => {
test("should validate when creating DeltaV1 from network image", () => {
it("should validate when creating DeltaV1 from network image", () => {
const invalidDelta = {
id: "id",
timeCreated: "not-a-number",
@ -322,7 +322,7 @@ describe("Delta Validation", () => {
expect(() => DeltaV1.fromNetworkImage(invalidDelta as never)).toThrow(InvalidDeltaFormatError);
});
test("should validate when creating DeltaV2 from network image", () => {
it("should validate when creating DeltaV2 from network image", () => {
const invalidDelta = {
id: "id",
timeCreated: 123,
@ -334,7 +334,7 @@ describe("Delta Validation", () => {
expect(() => DeltaV2.fromNetworkImage(invalidDelta as never)).toThrow(InvalidDeltaFormatError);
});
test("should accept valid network images", () => {
it("should accept valid network images", () => {
const validV1 = {
id: "uuid-123",
timeCreated: 123456789,

6
__tests__/unit/core/delta/delta.test.ts
View File

@ -1,8 +1,8 @@
import { createDelta } from '@src/core/delta-builder';
import { createDelta } from '../../../../src/core/delta-builder';
import {DeltaV1, DeltaV2} from "../../../../src";
describe("Delta", () => {
test("can convert DeltaV1 to DeltaV2", () => {
it("can convert DeltaV1 to DeltaV2", () => {
const deltaV1 = createDelta('a', 'h')
.addPointer('color', 'red')
.addPointer('furniture', 'chair-1', 'color')
@ -19,7 +19,7 @@ describe("Delta", () => {
});
});
test("can convert DeltaV2 to DeltaV1", () => {
it("can convert DeltaV2 to DeltaV1", () => {
const deltaV2 = createDelta('a', 'h')
.addPointer('color', 'red')
.addPointer('furniture', 'chair-1', 'color')

18
__tests__/unit/core/json-ast.test.ts
View File

@ -1,8 +1,8 @@
import { jsonToAst } from '@src/utils/json-ast';
import { JsonNode } from '@src/utils/json-ast/types';
import { jsonToAst } from '../../../src/utils/json-ast';
import { JsonNode } from '../../../src/utils/json-ast/types';
describe('jsonToAst', () => {
test('should handle primitive values', () => {
it('should handle primitive values', () => {
expect(jsonToAst(42)).toMatchObject({
type: 'number',
value: 42
@ -24,7 +24,7 @@ describe('jsonToAst', () => {
});
});
test('should handle empty objects and arrays', () => {
it('should handle empty objects and arrays', () => {
const emptyObj = jsonToAst({});
expect(emptyObj).toMatchObject({
type: 'object',
@ -38,7 +38,7 @@ describe('jsonToAst', () => {
});
});
test('should handle nested objects', () => {
it('should handle nested objects', () => {
const ast = jsonToAst({
name: 'test',
nested: { value: 42 }
@ -68,7 +68,7 @@ describe('jsonToAst', () => {
});
});
test('should handle arrays', () => {
it('should handle arrays', () => {
const ast = jsonToAst([1, 'two', true]);
expect(ast.type).toBe('array');
@ -90,7 +90,7 @@ describe('jsonToAst', () => {
});
});
test('should include paths when includePath is true', () => {
it('should include paths when includePath is true', () => {
const ast = jsonToAst({
user: {
name: 'test',
@ -116,7 +116,7 @@ describe('jsonToAst', () => {
expect(rolesNode?.children?.[0].path).toBe('user.roles[0]');
});
test('should respect maxDepth option', () => {
it('should respect maxDepth option', () => {
const deepObject = {
level1: {
level2: {
@ -139,7 +139,7 @@ describe('jsonToAst', () => {
expect(level2?.path).toBe('level1.level2');
});
test('should apply filter function when provided', () => {
it('should apply filter function when provided', () => {
const data = {
name: 'test',
age: 42,

62
__tests__/unit/core/negation.test.ts
View File

@ -1,8 +1,8 @@
import Debug from 'debug';
import { createDelta } from '@src/core/delta-builder';
import { NegationHelper } from '@src/features';
import { RhizomeNode } from '@src/node';
import { Lossless } from '@src/views';
import { createDelta } from '../../../src/core/delta-builder';
import { NegationHelper } from '../../../src/features';
import { RhizomeNode } from '../../../src/node';
import { Lossless } from '../../../src/views';
const debug = Debug('rz:negation:test');
@ -16,7 +16,7 @@ describe('Negation System', () => {
});
describe('Negation Helper', () => {
test('should create negation deltas correctly', () => {
it('should create negation deltas correctly', () => {
const originalDelta = createDelta('user1', 'host1')
.setProperty('entity1', 'name', 'Alice')
.buildV1();
@ -35,7 +35,7 @@ describe('Negation System', () => {
expect(NegationHelper.isNegationDelta(negationDelta)).toBe(true);
});
test('should identify negation deltas', () => {
it('should identify negation deltas', () => {
const regularDelta = createDelta('user1', 'host1')
.setProperty('entity1', 'name', 'Entity 1')
.buildV1();
@ -48,7 +48,7 @@ describe('Negation System', () => {
expect(NegationHelper.isNegationDelta(negationDelta)).toBe(true);
});
test('should extract negated delta ID', () => {
it('should extract negated delta ID', () => {
const targetDeltaId = 'target-delta-123';
const negationDelta = createDelta('moderator', 'host1')
.negate(targetDeltaId)
@ -64,7 +64,7 @@ describe('Negation System', () => {
expect(NegationHelper.getNegatedDeltaId(regularDelta)).toBeNull();
});
test('should find negations for specific deltas', () => {
it('should find negations for specific deltas', () => {
const delta1 = createDelta('user1', 'host1')
.setProperty('entity1', 'name', 'Entity 1')
.buildV1();
@ -89,7 +89,7 @@ describe('Negation System', () => {
expect(negationsForDelta2[0].id).toBe(negation3.id);
});
test('should check if deltas are negated', () => {
it('should check if deltas are negated', () => {
const delta1 = createDelta('user1', 'host1')
.setProperty('entity1', 'name', 'Entity 1')
.buildV1();
@ -105,7 +105,7 @@ describe('Negation System', () => {
expect(NegationHelper.isDeltaNegated(delta2.id, allDeltas)).toBe(false);
});
test('should filter out negated deltas', () => {
it('should filter out negated deltas', () => {
const delta1 = createDelta('user1', 'host1')
.setProperty('entity1', 'name', 'Entity 1')
.buildV1();
@ -129,7 +129,7 @@ describe('Negation System', () => {
expect(filtered[0].id).toBe(delta3.id);
});
test('should provide negation statistics', () => {
it('should provide negation statistics', () => {
const delta1 = createDelta('user1', 'host1')
.setProperty('entity1', 'name', 'Entity 1')
.buildV1();
@ -151,7 +151,7 @@ describe('Negation System', () => {
expect(stats.negationMap.get(delta1.id)).toContain(negation1.id);
});
test('should apply negations chronologically', () => {
it('should apply negations chronologically', () => {
const baseTime = Date.now();
// Create deltas with specific timestamps
@ -180,7 +180,7 @@ describe('Negation System', () => {
});
describe('Lossless View Integration', () => {
test('should filter negated deltas in lossless views', () => {
it('should filter negated deltas in lossless views', () => {
// Create original delta
const originalDelta = createDelta('user1', 'host1')
.setProperty('user123', 'name', 'Alice')
@ -203,7 +203,7 @@ describe('Negation System', () => {
lossless.ingestDelta(nonNegatedDelta);
// Get view - should only show non-negated delta
const view = lossless.compose(['user123']);
const view = lossless.view(['user123']);
expect(view.user123).toBeDefined();
@ -212,7 +212,7 @@ describe('Negation System', () => {
expect(view.user123.propertyDeltas.name).toBeUndefined();
});
test('should handle multiple negations of the same delta', () => {
it('should handle multiple negations of the same delta', () => {
const originalDelta = createDelta('user1', 'host1')
.setProperty('post1', 'content', 'Original content')
.buildV1();
@ -224,13 +224,13 @@ describe('Negation System', () => {
lossless.ingestDelta(negation1);
lossless.ingestDelta(negation2);
const view = lossless.compose(['post1']);
const view = lossless.view(['post1']);
// Original delta should be negated (not visible)
expect(view.post1).toBeUndefined();
});
test('should provide negation statistics for entities', () => {
it('should provide negation statistics for entities', () => {
const delta1 = createDelta('user1', 'host1')
.setProperty('article1', 'title', 'Original Title')
.buildV1();
@ -255,7 +255,7 @@ describe('Negation System', () => {
expect(stats.negationsByProperty.content.negated).toBe(0);
});
test('should retrieve negation deltas for entities', () => {
it('should retrieve negation deltas for entities', () => {
const originalDelta = createDelta('user1', 'host1')
.setProperty('task1', 'status', 'pending')
.buildV1();
@ -271,7 +271,7 @@ describe('Negation System', () => {
expect(negations[0].creator).toBe('admin');
});
test('should handle negation in transactions', () => {
it('should handle negation in transactions', () => {
const transactionId = 'tx-negation';
// Create transaction declaration
@ -298,11 +298,11 @@ describe('Negation System', () => {
lossless.ingestDelta(negationDelta);
// Transaction should complete, but original delta should be negated
const view = lossless.compose(['post1']);
const view = lossless.view(['post1']);
expect(view.post1).toBeUndefined(); // No visible deltas
});
test('should handle chronological negation scenarios', () => {
it('should handle chronological negation scenarios', () => {
const baseTime = Date.now();
// User posts content
@ -325,7 +325,7 @@ describe('Negation System', () => {
lossless.ingestDelta(negationDelta);
lossless.ingestDelta(editDelta);
const view = lossless.compose(['post1']);
const view = lossless.view(['post1']);
// Should show edited content (edit happened after negation)
expect(view.post1).toBeDefined();
@ -338,7 +338,7 @@ describe('Negation System', () => {
});
describe('Edge Cases', () => {
test('should handle negation of non-existent deltas', () => {
it('should handle negation of non-existent deltas', () => {
const negationDelta = createDelta('moderator', 'host1').negate('non-existent-delta-id').buildV1();
lossless.ingestDelta(negationDelta);
@ -348,7 +348,7 @@ describe('Negation System', () => {
expect(stats.negationDeltas).toBe(0); // No negations for this entity
});
test('should handle self-referential entities in negations', () => {
it('should handle self-referential entities in negations', () => {
// Create a delta that references itself
const selfRefDelta = createDelta('user1', 'host1')
.setProperty('node1', 'parent', 'node1')
@ -360,11 +360,11 @@ describe('Negation System', () => {
lossless.ingestDelta(selfRefDelta);
lossless.ingestDelta(negationDelta);
const view = lossless.compose(['node1']);
const view = lossless.view(['node1']);
expect(view.node1).toBeUndefined(); // Should be negated
});
test('should handle multiple direct negations of the same delta', () => {
it('should handle multiple direct negations of the same delta', () => {
const testNode = new RhizomeNode();
const testLossless = new Lossless(testNode);
@ -383,7 +383,7 @@ describe('Negation System', () => {
testLossless.ingestDelta(negation2);
// Get the view after processing all deltas
const view = testLossless.compose(['entity2']);
const view = testLossless.view(['entity2']);
// The original delta should be negated (not in view) because it has two direct negations
expect(view.entity2).toBeUndefined();
@ -395,7 +395,7 @@ describe('Negation System', () => {
expect(stats.effectiveDeltas).toBe(0);
});
test('should handle complex negation chains', () => {
it('should handle complex negation chains', () => {
const testNode = new RhizomeNode();
const testLossless = new Lossless(testNode);
@ -421,7 +421,7 @@ describe('Negation System', () => {
testLossless.ingestDelta(deltaD);
// Get the view after processing all deltas
const view = testLossless.compose(['entity3']);
const view = testLossless.view(['entity3']);
// The original delta should be negated because:
// - B negates A
@ -468,7 +468,7 @@ describe('Negation System', () => {
expect(stats.effectiveDeltas).toBe(0);
});
test('should handle multiple independent negations', () => {
it('should handle multiple independent negations', () => {
const testNode = new RhizomeNode();
const testLossless = new Lossless(testNode);
@ -492,7 +492,7 @@ describe('Negation System', () => {
testLossless.ingestDelta(negation2);
// Get the view after processing all deltas
const view = testLossless.compose(['entity4']);
const view = testLossless.view(['entity4']);
// Both deltas should be negated
expect(view.entity4).toBeUndefined();

8
__tests__/unit/core/peer-address.test.ts
View File

@ -1,18 +1,18 @@
import {parseAddressList, PeerAddress} from '@src/network/peers';
import {parseAddressList, PeerAddress} from '../../../src/network/peers';
describe('PeerAddress', () => {
test('toString()', () => {
it('toString()', () => {
const addr = new PeerAddress('localhost', 1000);
expect(addr.toAddrString()).toBe("localhost:1000");
});
test('fromString()', () => {
it('fromString()', () => {
const addr = PeerAddress.fromString("localhost:1000");
expect(addr.addr).toBe("localhost");
expect(addr.port).toBe(1000);
});
test('parseAddressList()', () => {
it('parseAddressList()', () => {
const input = "255.255.255.255:99999, 0.0.0.0:0";
const result = parseAddressList(input);
expect(result).toHaveLength(2);

52
__tests__/unit/core/transactions.test.ts
View File

@ -1,7 +1,7 @@
import { createDelta } from '@src/core/delta-builder';
import { Lossless } from '@src/views';
import { RhizomeNode } from '@src/node';
import { DeltaFilter } from '@src/core';
import { createDelta } from '../../../src/core/delta-builder';
import { Lossless } from '../../../src/views';
import { RhizomeNode } from '../../../src/node';
import { DeltaFilter } from '../../../src/core';
describe('Transactions', () => {
let node: RhizomeNode;
@ -13,7 +13,7 @@ describe('Transactions', () => {
});
describe('Transaction-based filtering', () => {
test('should exclude deltas from incomplete transactions', () => {
it('should exclude deltas from incomplete transactions', () => {
const transactionId = 'tx-123';
// Create a delta that declares a transaction with size 3
@ -39,7 +39,7 @@ describe('Transactions', () => {
lossless.ingestDelta(delta2);
// View should be empty because transaction is incomplete (2/3 deltas)
const view = lossless.compose(['user123']);
const view = lossless.view(['user123']);
expect(view.user123).toBeUndefined();
// Add the third delta to complete the transaction
@ -51,14 +51,14 @@ describe('Transactions', () => {
lossless.ingestDelta(delta3);
// Now the view should include all deltas from the completed transaction
const completeView = lossless.compose(['user123']);
const completeView = lossless.view(['user123']);
expect(completeView.user123).toBeDefined();
expect(completeView.user123.propertyDeltas.name).toHaveLength(1);
expect(completeView.user123.propertyDeltas.age).toHaveLength(1);
expect(completeView.user123.propertyDeltas.email).toHaveLength(1);
});
test('should handle multiple transactions independently', () => {
it('should handle multiple transactions independently', () => {
const tx1 = 'tx-001';
const tx2 = 'tx-002';
@ -87,7 +87,7 @@ describe('Transactions', () => {
);
// Neither transaction is complete
let view = lossless.compose(['order1', 'order2']);
let view = lossless.view(['order1', 'order2']);
expect(view.order1).toBeUndefined();
expect(view.order2).toBeUndefined();
@ -99,7 +99,7 @@ describe('Transactions', () => {
);
// tx1 is complete, tx2 is not
view = lossless.compose(['order1', 'order2']);
view = lossless.view(['order1', 'order2']);
expect(view.order1).toBeDefined();
expect(view.order1.propertyDeltas.status).toHaveLength(1);
expect(view.order1.propertyDeltas.total).toHaveLength(1);
@ -113,14 +113,14 @@ describe('Transactions', () => {
);
// Both transactions complete
view = lossless.compose(['order1', 'order2']);
view = lossless.view(['order1', 'order2']);
expect(view.order1).toBeDefined();
expect(view.order2).toBeDefined();
expect(view.order2.propertyDeltas.status).toHaveLength(1);
expect(view.order2.propertyDeltas.tracking).toHaveLength(1);
});
test('should work with transaction-aware delta filters', () => {
it('should work with transaction-aware delta filters', () => {
const transactionId = 'tx-filter-test';
// Create transaction with 2 deltas
@ -147,7 +147,7 @@ describe('Transactions', () => {
// With incomplete transaction, nothing should show
// But once complete, the filter should still apply
const view = lossless.compose(['doc1'], userFilter);
const view = lossless.view(['doc1'], userFilter);
// Even though transaction is complete, only delta from user1 should appear
expect(view.doc1).toBeDefined();
@ -155,7 +155,7 @@ describe('Transactions', () => {
expect(view.doc1.propertyDeltas.author).toBeUndefined();
});
test('should handle transaction with deltas affecting multiple entities', () => {
it('should handle transaction with deltas affecting multiple entities', () => {
const transactionId = 'tx-multi-entity';
// Transaction that updates multiple entities atomically
@ -182,7 +182,7 @@ describe('Transactions', () => {
);
// Transaction incomplete - no entities should show updates
let view = lossless.compose(['account1', 'account2']);
let view = lossless.view(['account1', 'account2']);
expect(view.account1).toBeUndefined();
expect(view.account2).toBeUndefined();
@ -197,7 +197,7 @@ describe('Transactions', () => {
);
// All entities should now be visible
view = lossless.compose(['account1', 'account2', 'transfer123']);
view = lossless.view(['account1', 'account2', 'transfer123']);
expect(view.account1).toBeDefined();
expect(view.account1.propertyDeltas.balance).toHaveLength(1);
expect(view.account2).toBeDefined();
@ -206,7 +206,7 @@ describe('Transactions', () => {
expect(view.transfer123.propertyDeltas.details).toHaveLength(1);
});
test('should emit events only when transactions complete', async () => {
it('should emit events only when transactions complete', async () => {
const transactionId = 'tx-events';
const updateEvents: Array<{ entityId: string, deltaIds: string[] }> = [];
@ -252,7 +252,7 @@ describe('Transactions', () => {
expect(entity1Update!.deltaIds).toContain(delta2.id);
});
test('should support waiting for transaction completion', async () => {
it('should support waiting for transaction completion', async () => {
const transactionId = 'tx-wait';
// Create transaction
@ -289,12 +289,12 @@ describe('Transactions', () => {
expect(isResolved).toBe(true);
// View should show completed transaction
const view = lossless.compose(['job1']);
const view = lossless.view(['job1']);
expect(view.job1).toBeDefined();
expect(view.job1.propertyDeltas.status).toHaveLength(2);
});
test('should handle non-transactional deltas normally', () => {
it('should handle non-transactional deltas normally', () => {
// Regular delta without transaction
const regularDelta = createDelta('user1', 'host1')
.addPointer('name', 'user456', 'name')
@ -309,7 +309,7 @@ describe('Transactions', () => {
lossless.ingestDelta(regularDelta);
// Should immediately appear in view
const view = lossless.compose(['user456']);
const view = lossless.view(['user456']);
expect(view.user456).toBeDefined();
expect(view.user456.propertyDeltas.name).toHaveLength(1);
@ -319,7 +319,7 @@ describe('Transactions', () => {
});
describe('Transaction edge cases', () => {
test('should handle transaction size updates', () => {
it('should handle transaction size updates', () => {
const transactionId = 'tx-resize';
// Initially declare transaction with size 2
@ -345,11 +345,11 @@ describe('Transactions', () => {
expect(lossless.transactions.isComplete(transactionId)).toBe(true);
// View should show the cart
const view = lossless.compose(['cart1']);
const view = lossless.view(['cart1']);
expect(view.cart1).toBeDefined();
});
test('should handle missing transaction size gracefully', () => {
it('should handle missing transaction size gracefully', () => {
const transactionId = 'tx-no-size';
// Add delta with transaction reference but no size declaration
@ -363,7 +363,7 @@ describe('Transactions', () => {
expect(lossless.transactions.isComplete(transactionId)).toBe(false);
// Delta should not appear in view
const view = lossless.compose(['entity1']);
const view = lossless.view(['entity1']);
expect(view.entity1).toBeUndefined();
// Declare size after the fact
@ -376,7 +376,7 @@ describe('Transactions', () => {
expect(lossless.transactions.isComplete(transactionId)).toBe(true);
// And delta should appear in view
const viewAfter = lossless.compose(['entity1']);
const viewAfter = lossless.view(['entity1']);
expect(viewAfter.entity1).toBeDefined();
});
});

44
__tests__/unit/query/query.test.ts
View File

@ -1,10 +1,10 @@
import { QueryEngine } from '@src/query';
import { Lossless } from '@src/views';
import { DefaultSchemaRegistry } from '@src/schema';
import { SchemaBuilder, PrimitiveSchemas } from '@src/schema';
import { QueryEngine } from '../../../src/query';
import { Lossless } from '../../../src/views';
import { DefaultSchemaRegistry } from '../../../src/schema';
import { SchemaBuilder, PrimitiveSchemas } from '../../../src/schema';
import { CommonSchemas } from '../../../util/schemas';
import { createDelta } from '@src/core/delta-builder';
import { RhizomeNode } from '@src/node';
import { createDelta } from '../../../src/core/delta-builder';
import { RhizomeNode } from '../../../src/node';
describe('Query Engine', () => {
let queryEngine: QueryEngine;
@ -111,7 +111,7 @@ describe('Query Engine', () => {
}
describe('Basic Query Operations', () => {
test('can query all entities of a schema type', async () => {
it('can query all entities of a schema type', async () => {
// Create test users
await createUser('user1', 'Alice', 25, 'alice@example.com');
await createUser('user2', 'Bob', 30);
@ -127,7 +127,7 @@ describe('Query Engine', () => {
expect(result.entities['user3']).toBeDefined();
});
test('can query a single entity by ID', async () => {
it('can query a single entity by ID', async () => {
await createUser('user1', 'Alice', 25, 'alice@example.com');
const result = await queryEngine.queryOne('user', 'user1');
@ -139,7 +139,7 @@ describe('Query Engine', () => {
expect(result?.propertyDeltas.email).toBeDefined();
});
test('returns null for non-existent entity', async () => {
it('returns null for non-existent entity', async () => {
const result = await queryEngine.queryOne('user', 'nonexistent');
expect(result).toBeNull();
});
@ -154,7 +154,7 @@ describe('Query Engine', () => {
await createUser('user4', 'Diana', 20);
});
test('can filter by primitive property values', async () => {
it('can filter by primitive property values', async () => {
// Find users older than 28
const result = await queryEngine.query('user', {
'>': [{ 'var': 'age' }, 28]
@ -167,7 +167,7 @@ describe('Query Engine', () => {
expect(result.entities['user4']).toBeUndefined(); // Diana, 20
});
test('can filter by string properties', async () => {
it('can filter by string properties', async () => {
// Find users with name starting with 'A' - using substring check instead of startsWith
const result = await queryEngine.query('user', {
'in': ['A', { 'var': 'name' }]
@ -177,7 +177,7 @@ describe('Query Engine', () => {
expect(result.entities['user1']).toBeDefined(); // Alice
});
test('can filter by null/missing properties', async () => {
it('can filter by null/missing properties', async () => {
// Find users without email
const result = await queryEngine.query('user', {
'==': [{ 'var': 'email' }, null]
@ -187,7 +187,7 @@ describe('Query Engine', () => {
expect(result.entities['user4']).toBeDefined(); // Diana has no email
});
test('can use complex logic expressions', async () => {
it('can use complex logic expressions', async () => {
// Find users who are (older than 30) OR (younger than 25 AND have email)
const result = await queryEngine.query('user', {
'or': [
@ -216,7 +216,7 @@ describe('Query Engine', () => {
await createBlogPost('post4', 'Popular Post', 'charlie', true, 1000);
});
test('can filter published posts', async () => {
it('can filter published posts', async () => {
const result = await queryEngine.query('blog-post', {
'==': [{ 'var': 'published' }, true]
});
@ -228,7 +228,7 @@ describe('Query Engine', () => {
expect(result.entities['post3']).toBeUndefined(); // Draft
});
test('can filter by author', async () => {
it('can filter by author', async () => {
const result = await queryEngine.query('blog-post', {
'==': [{ 'var': 'author' }, 'alice']
});
@ -238,7 +238,7 @@ describe('Query Engine', () => {
expect(result.entities['post3']).toBeDefined();
});
test('can filter by view count ranges', async () => {
it('can filter by view count ranges', async () => {
// Posts with more than 100 views
const result = await queryEngine.query('blog-post', {
'>': [{ 'var': 'views' }, 100]
@ -257,7 +257,7 @@ describe('Query Engine', () => {
}
});
test('can limit query results', async () => {
it('can limit query results', async () => {
const result = await queryEngine.query('user', undefined, { maxResults: 5 });
expect(result.totalFound).toBe(10);
@ -265,7 +265,7 @@ describe('Query Engine', () => {
expect(Object.keys(result.entities)).toHaveLength(5);
});
test('respects delta filters', async () => {
it('respects delta filters', async () => {
const result = await queryEngine.query('user', undefined, {
deltaFilter: (delta) => delta.creator === 'test'
});
@ -276,7 +276,7 @@ describe('Query Engine', () => {
});
describe('Statistics', () => {
test('provides query engine statistics', async () => {
it('provides query engine statistics', async () => {
await createUser('user1', 'Alice', 25);
await createBlogPost('post1', 'Test Post', 'alice', true, 50);
@ -290,13 +290,13 @@ describe('Query Engine', () => {
});
describe('Error Handling', () => {
test('handles invalid schema IDs gracefully', async () => {
it('handles invalid schema IDs gracefully', async () => {
const result = await queryEngine.query('nonexistent-schema');
expect(result.totalFound).toBe(0);
expect(Object.keys(result.entities)).toHaveLength(0);
});
test('rejects invalid JSON Logic operators', async () => {
it('rejects invalid JSON Logic operators', async () => {
await createUser('user1', 'Alice', 25);
// Should throw an error for invalid operator
@ -307,7 +307,7 @@ describe('Query Engine', () => {
).rejects.toThrow('Invalid query operator: invalid-operator');
});
test('handles valid JSON Logic expressions with runtime errors', async () => {
it('handles valid JSON Logic expressions with runtime errors', async () => {
await createUser('user1', 'Alice', 25);
// This is a valid operator but will cause a runtime error due to type mismatch

32
__tests__/unit/views/lossless.test.ts
View File

@ -1,12 +1,12 @@
import {DeltaFilter} from '@src/core';
import {Lossless} from '@src/views';
import {RhizomeNode} from '@src/node';
import {createDelta} from '@src/core/delta-builder';
import {DeltaFilter} from '../../../src/core';
import {Lossless} from '../../../src/views';
import {RhizomeNode} from '../../../src/node';
import {createDelta} from '../../../src/core/delta-builder';
describe('Lossless', () => {
const node = new RhizomeNode();
test('creates a lossless view of keanu as neo in the matrix', () => {
it('creates a lossless view of keanu as neo in the matrix', () => {
const delta = createDelta('a', 'h')
.addPointer('actor', 'keanu', 'roles')
.addPointer('role', 'neo', 'actor')
@ -39,7 +39,7 @@ describe('Lossless', () => {
lossless.ingestDelta(delta);
expect(lossless.compose()).toMatchObject({
expect(lossless.view()).toMatchObject({
keanu: {
referencedAs: ["actor"],
propertyDeltas: {
@ -91,7 +91,7 @@ describe('Lossless', () => {
});
});
test('accepts DeltaV2 instances', () => {
it('accepts DeltaV2 instances', () => {
const delta = createDelta('a', 'h')
.addPointer('actor', 'keanu', 'roles')
.addPointer('role', 'neo', 'actor')
@ -104,7 +104,7 @@ describe('Lossless', () => {
lossless.ingestDelta(delta);
expect(lossless.compose()).toMatchObject({
expect(lossless.view()).toMatchObject({
keanu: {
referencedAs: ["actor"],
propertyDeltas: {
@ -175,7 +175,7 @@ describe('Lossless', () => {
.buildV1()
);
expect(lossless.compose()).toMatchObject({
expect(lossless.view()).toMatchObject({
ace: {
referencedAs: ["1", "14"],
propertyDeltas: {
@ -197,12 +197,12 @@ describe('Lossless', () => {
});
});
test('filter by creator and host', () => {
it('filter by creator and host', () => {
const filter: DeltaFilter = ({creator, host}) => {
return creator === 'A' && host === 'H';
};
expect(lossless.compose(undefined, filter)).toMatchObject({
expect(lossless.view(undefined, filter)).toMatchObject({
ace: {
referencedAs: ["1"],
propertyDeltas: {
@ -217,7 +217,7 @@ describe('Lossless', () => {
}
});
expect(lossless.compose(["ace"], filter)).toMatchObject({
expect(lossless.view(["ace"], filter)).toMatchObject({
ace: {
referencedAs: ["1"],
propertyDeltas: {
@ -233,7 +233,7 @@ describe('Lossless', () => {
});
});
test('filter with transactions', () => {
it('filter with transactions', () => {
const losslessT = new Lossless(node);
const transactionId = 'tx-filter-test';
@ -261,7 +261,7 @@ describe('Lossless', () => {
);
// Transaction incomplete - nothing should show
const incompleteView = losslessT.compose(['process1']);
const incompleteView = losslessT.view(['process1']);
expect(incompleteView.process1).toBeUndefined();
// A2: Second delta from creator A completes transaction
@ -274,13 +274,13 @@ describe('Lossless', () => {
);
// All deltas visible now
const completeView = losslessT.compose(['process1']);
const completeView = losslessT.view(['process1']);
expect(completeView.process1).toBeDefined();
expect(completeView.process1.propertyDeltas.status).toHaveLength(3);
// Filter by creator A only
const filterA: DeltaFilter = ({creator}) => creator === 'A';
const filteredView = losslessT.compose(['process1'], filterA);
const filteredView = losslessT.view(['process1'], filterA);
expect(filteredView.process1).toBeDefined();
expect(filteredView.process1.propertyDeltas.status).toHaveLength(2);

4
__tests__/unit/views/lossy.test.ts
View File

@ -6,7 +6,7 @@ import { RhizomeNode } from "../../../src/node";
import { valueFromCollapsedDelta } from "../../../src/views/resolvers/aggregation-resolvers";
import { lastValueFromDeltas } from "../../../src/views/resolvers/timestamp-resolvers";
import { createDelta } from "../../../src/core/delta-builder";
const debug = Debug('rz:test:lossy');
const debug = Debug('test:lossy');
type Role = {
actor: PointerTarget,
@ -69,7 +69,7 @@ describe('Lossy', () => {
);
});
test('example summary', () => {
it('example summary', () => {
const result = lossy.resolve();
debug('result', result);
expect(result).toEqual({

24
__tests__/unit/views/multi-pointer-resolution.test.ts
View File

@ -4,11 +4,11 @@
* between multiple entities and includes scalar values.
*/
import { RhizomeNode } from '@src/node';
import { createDelta } from '@src/core/delta-builder';
import { DefaultSchemaRegistry } from '@src/schema';
import { SchemaBuilder, PrimitiveSchemas, ReferenceSchemas, SchemaAppliedViewWithNesting } from '@src/schema';
import { TypedCollectionImpl } from '@src/collections';
import { RhizomeNode } from '../../../src/node';
import { createDelta } from '../../../src/core/delta-builder';
import { DefaultSchemaRegistry } from '../../../src/schema';
import { SchemaBuilder, PrimitiveSchemas, ReferenceSchemas, SchemaAppliedViewWithNesting } from '../../../src/schema';
import { TypedCollectionImpl } from '../../../src/collections';
describe('Multi-Pointer Delta Resolution', () => {
let node: RhizomeNode;
@ -20,7 +20,7 @@ describe('Multi-Pointer Delta Resolution', () => {
});
describe('Three-Entity Relationship Deltas', () => {
test('should handle movie casting deltas with actor, movie, role, and scalars', async () => {
it('should handle movie casting deltas with actor, movie, role, and scalars', async () => {
// Create schemas for a movie casting scenario
const actorSchema = SchemaBuilder
.create('actor')
@ -86,7 +86,7 @@ describe('Multi-Pointer Delta Resolution', () => {
node.lossless.ingestDelta(castingDelta);
// Test from Keanu's perspective
const keanuViews = node.lossless.compose(['keanu']);
const keanuViews = node.lossless.view(['keanu']);
const keanuView = keanuViews['keanu'];
expect(keanuView.propertyDeltas.filmography).toBeDefined();
@ -115,7 +115,7 @@ describe('Multi-Pointer Delta Resolution', () => {
}
// Test from Matrix's perspective
const matrixViews = node.lossless.compose(['matrix']);
const matrixViews = node.lossless.view(['matrix']);
const matrixView = matrixViews['matrix'];
const nestedMatrixView = schemaRegistry.applySchemaWithNesting(
@ -129,7 +129,7 @@ describe('Multi-Pointer Delta Resolution', () => {
expect(nestedMatrixView.nestedObjects.cast).toBeDefined();
});
test('should handle deltas with mixed scalar and reference values correctly', async () => {
it('should handle deltas with mixed scalar and reference values correctly', async () => {
// Create a simpler schema for testing mixed values
const personSchema = SchemaBuilder
.create('person')
@ -170,7 +170,7 @@ describe('Multi-Pointer Delta Resolution', () => {
node.lossless.ingestDelta(relationshipDelta);
// Test from Alice's perspective
const aliceViews = node.lossless.compose(['alice']);
const aliceViews = node.lossless.view(['alice']);
const aliceView = aliceViews['alice'];
const nestedAliceView = schemaRegistry.applySchemaWithNesting(
@ -198,7 +198,7 @@ describe('Multi-Pointer Delta Resolution', () => {
}
});
test('should correctly identify multiple entity references within a single delta', async () => {
it('should correctly identify multiple entity references within a single delta', async () => {
// Test a scenario with multiple entity references that should all be resolved
const projectSchema = SchemaBuilder
.create('project')
@ -245,7 +245,7 @@ describe('Multi-Pointer Delta Resolution', () => {
node.lossless.ingestDelta(collaborationDelta);
// Test from project's perspective
const projectViews = node.lossless.compose(['website']);
const projectViews = node.lossless.view(['website']);
const projectView = projectViews['website'];
const nestedProjectView = schemaRegistry.applySchemaWithNesting(

38
__tests__/unit/views/nested-resolution.test.ts
View File

@ -9,12 +9,12 @@
* - Deep nesting scenarios
*/
import { RhizomeNode } from '@src/node';
import { DefaultSchemaRegistry } from '@src/schema';
import { SchemaBuilder, PrimitiveSchemas, ReferenceSchemas } from '@src/schema';
import { RhizomeNode } from '../../../src/node';
import { DefaultSchemaRegistry } from '../../../src/schema';
import { SchemaBuilder, PrimitiveSchemas, ReferenceSchemas } from '../../../src/schema';
import { CommonSchemas } from '../../../util/schemas';
import { TypedCollectionImpl } from '@src/collections';
import { createDelta } from '@src/core/delta-builder';
import { TypedCollectionImpl } from '../../../src/collections';
import { createDelta } from '../../../src/core/delta-builder';
describe('Nested Object Resolution', () => {
let node: RhizomeNode;
@ -35,7 +35,7 @@ describe('Nested Object Resolution', () => {
});
describe('Basic Reference Resolution', () => {
test('should resolve single-level user references with UserSummary schema', async () => {
it('should resolve single-level user references with UserSummary schema', async () => {
const userCollection = new TypedCollectionImpl<{
name: string;
email?: string;
@ -62,7 +62,7 @@ describe('Nested Object Resolution', () => {
node.lossless.ingestDelta(friendshipDelta);
// Get Alice's lossless view
const aliceViews = node.lossless.compose(['alice']);
const aliceViews = node.lossless.view(['alice']);
const aliceView = aliceViews['alice'];
expect(aliceView).toBeDefined();
@ -92,7 +92,7 @@ describe('Nested Object Resolution', () => {
}
});
test('should handle missing references gracefully', async () => {
it('should handle missing references gracefully', async () => {
const userCollection = new TypedCollectionImpl<{
name: string;
friends?: string[];
@ -109,7 +109,7 @@ describe('Nested Object Resolution', () => {
.buildV1();
node.lossless.ingestDelta(friendshipDelta);
const aliceViews = node.lossless.compose(['alice']);
const aliceViews = node.lossless.view(['alice']);
const aliceView = aliceViews['alice'];
const nestedView = schemaRegistry.applySchemaWithNesting(
@ -129,7 +129,7 @@ describe('Nested Object Resolution', () => {
});
describe('Depth Limiting', () => {
test('should respect maxDepth parameter and truncate deep nesting', async () => {
it('should respect maxDepth parameter and truncate deep nesting', async () => {
// Create a custom schema with deeper nesting for testing
const deepUserSchema = SchemaBuilder
.create('deep-user')
@ -167,7 +167,7 @@ describe('Nested Object Resolution', () => {
.buildV1();
node.lossless.ingestDelta(mentorshipDelta2);
const aliceViews = node.lossless.compose(['alice']);
const aliceViews = node.lossless.view(['alice']);
const aliceView = aliceViews['alice'];
// Test with maxDepth = 1 (should only resolve Alice and Bob)
@ -217,7 +217,7 @@ describe('Nested Object Resolution', () => {
});
describe('Circular Reference Prevention', () => {
test('should detect and prevent circular references', async () => {
it('should detect and prevent circular references', async () => {
const userCollection = new TypedCollectionImpl<{
name: string;
friends?: string[];
@ -242,7 +242,7 @@ describe('Nested Object Resolution', () => {
.buildV1();
node.lossless.ingestDelta(friendship2);
const aliceViews = node.lossless.compose(['alice']);
const aliceViews = node.lossless.view(['alice']);
const aliceView = aliceViews['alice'];
// Should handle circular reference without infinite recursion
@ -260,7 +260,7 @@ describe('Nested Object Resolution', () => {
expect(nestedView.metadata?.truncated).toBeDefined();
});
test('should handle self-references correctly', async () => {
it('should handle self-references correctly', async () => {
const userCollection = new TypedCollectionImpl<{
name: string;
friends?: string[];
@ -277,7 +277,7 @@ describe('Nested Object Resolution', () => {
.buildV1();
node.lossless.ingestDelta(selfFriendship);
const aliceViews = node.lossless.compose(['alice']);
const aliceViews = node.lossless.view(['alice']);
const aliceView = aliceViews['alice'];
const nestedView = schemaRegistry.applySchemaWithNesting(
@ -293,7 +293,7 @@ describe('Nested Object Resolution', () => {
});
describe('Array References', () => {
test('should resolve arrays of references correctly', async () => {
it('should resolve arrays of references correctly', async () => {
const userCollection = new TypedCollectionImpl<{
name: string;
friends?: string[];
@ -319,7 +319,7 @@ describe('Nested Object Resolution', () => {
.buildV1();
node.lossless.ingestDelta(friendship2);
const aliceViews = node.lossless.compose(['alice']);
const aliceViews = node.lossless.view(['alice']);
const aliceView = aliceViews['alice'];
const nestedView = schemaRegistry.applySchemaWithNesting(
@ -348,7 +348,7 @@ describe('Nested Object Resolution', () => {
});
describe('Summary Schema Pattern', () => {
test('should use Summary schema to break infinite recursion', async () => {
it('should use Summary schema to break infinite recursion', async () => {
// The User schema references user-summary for friends
// This tests the pattern mentioned in the spec
const userCollection = new TypedCollectionImpl<{
@ -375,7 +375,7 @@ describe('Nested Object Resolution', () => {
.buildV1();
node.lossless.ingestDelta(friendship);
const aliceViews = node.lossless.compose(['alice']);
const aliceViews = node.lossless.view(['alice']);
const aliceView = aliceViews['alice'];
const nestedView = schemaRegistry.applySchemaWithNesting(

778
__tests__/unit/views/resolvers/custom-resolvers.test.ts Normal file
View File

@ -0,0 +1,778 @@
import { RhizomeNode, Lossless, createDelta } from "../../../../src";
import { CollapsedDelta } from "../../../../src/views/lossless";
import {
CustomResolver,
ResolverPlugin,
LastWriteWinsPlugin,
FirstWriteWinsPlugin,
ConcatenationPlugin,
MajorityVotePlugin,
MinPlugin,
MaxPlugin
} from "../../../../src/views/resolvers/custom-resolvers";
type PropertyTypes = string | number | boolean | null;
describe('Custom Resolvers', () => {
let node: RhizomeNode;
let lossless: Lossless;
beforeEach(() => {
node = new RhizomeNode();
lossless = new Lossless(node);
});
describe('Built-in Plugins', () => {
test('LastWriteWinsPlugin should resolve to most recent value', () => {
// First delta with earlier timestamp
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'name', 'first', 'collection')
.buildV1()
);
// Second delta with later timestamp (should win)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'name', 'second', 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
name: new LastWriteWinsPlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.name).toBe('second');
});
test('FirstWriteWinsPlugin should resolve to earliest value', () => {
// Later delta (should be ignored by FirstWriteWins)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'name', 'second', 'collection')
.buildV1()
);
// Earlier delta (should win with FirstWriteWins)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'name', 'first', 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
name: new FirstWriteWinsPlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.name).toBe('first');
});
test('ConcatenationPlugin should join string values chronologically', () => {
// First tag
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'tags', 'red', 'collection')
.buildV1()
);
// Second tag (with later timestamp)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(3000)
.setProperty('entity1', 'tags', 'blue', 'collection')
.buildV1()
);
// Third tag (with timestamp between first and second)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'tags', 'green', 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
tags: new ConcatenationPlugin(' ')
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.tags).toBe('red green blue');
});
test('ConcatenationPlugin should handle duplicates', () => {
// First tag
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'tags', 'red', 'collection')
.buildV1()
);
// Duplicate tag with later timestamp
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'tags', 'red', 'collection') // duplicate
.buildV1()
);
const resolver = new CustomResolver(lossless, {
tags: new ConcatenationPlugin(',')
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.tags).toBe('red'); // Should not duplicate
});
test('MajorityVotePlugin should resolve to most voted value', () => {
// Add 3 votes for 'red'
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'color', 'red', 'collection')
.buildV1()
);
lossless.ingestDelta(
createDelta('user2', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'color', 'red', 'collection')
.buildV1()
);
lossless.ingestDelta(
createDelta('user3', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'color', 'red', 'collection')
.buildV1()
);
// Add 2 votes for 'blue'
lossless.ingestDelta(
createDelta('user4', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'color', 'blue', 'collection')
.buildV1()
);
lossless.ingestDelta(
createDelta('user5', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'color', 'blue', 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
color: new MajorityVotePlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.color).toBe('red'); // 3 votes vs 2 votes
});
test('MinPlugin should resolve to minimum numeric value', () => {
// First score (100)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'score', 100, 'collection')
.buildV1()
);
// Second score (50) - this is the minimum
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'score', 50, 'collection')
.buildV1()
);
// Third score (75)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(3000)
.setProperty('entity1', 'score', 75, 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
score: new MinPlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.score).toBe(50);
});
test('MaxPlugin should resolve to maximum numeric value', () => {
// First score (100)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'score', 100, 'collection')
.buildV1()
);
// Second score (150) - this is the maximum
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'score', 150, 'collection')
.buildV1()
);
// Third score (75)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(3000)
.setProperty('entity1', 'score', 75, 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
score: new MaxPlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.score).toBe(150);
});
});
describe('Mixed Plugin Configurations', () => {
test('should handle different plugins for different properties', () => {
// Add name with different timestamps
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'name', 'old_name', 'collection')
.buildV1()
);
// Update name with newer timestamp
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'name', 'new_name', 'collection')
.buildV1()
);
// Add scores
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'score', 100, 'collection')
.buildV1()
);
// Add another score (MinPlugin will pick the smaller one)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'score', 50, 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
name: new LastWriteWinsPlugin(), // Should resolve to 'new_name'
score: new MinPlugin() // Should resolve to 50
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.name).toBe('new_name');
expect(result!['entity1'].properties.score).toBe(50);
});
test('should only include entities with configured properties', () => {
// Entity1 has configured property
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'name', 'test', 'collection')
.buildV1()
);
// Entity2 has non-configured property
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity2', 'other_prop', 'value', 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
name: new LastWriteWinsPlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1']).toBeDefined();
expect(result!['entity1'].properties.name).toBe('test');
expect(result!['entity2']).toBeUndefined(); // No configured properties
});
});
describe('Plugin Dependencies', () => {
test('should detect circular dependencies', () => {
class PluginA implements ResolverPlugin {
name = 'a';
dependencies = ['b'];
initialize() { return {}; }
update() { return {}; }
resolve() { return 'a'; }
}
class PluginB implements ResolverPlugin {
name = 'b';
dependencies = ['a'];
initialize() { return {}; }
update() { return {}; }
resolve() { return 'b'; }
}
expect(() => {
new CustomResolver(lossless, {
'a': new PluginA(),
'b': new PluginB()
});
}).toThrow('Circular dependency detected');
});
test('should process plugins in dependency order', () => {
// Enable debug logging for this test
process.env.DEBUG = 'rz:*';
const executionOrder: string[] = [];
// Create test plugins with dependency tracking
const pluginTracker = {
first: { updated: false, resolved: false },
second: { updated: false, resolved: false }
};
interface PluginState {
value: string;
updated: boolean;
resolved: boolean;
}
class FirstPlugin implements ResolverPlugin<PluginState> {
name = 'first';
dependencies: string[] = [];
initialize(): PluginState {
console.log('First plugin initialized');
executionOrder.push('first-init');
return { value: '', updated: false, resolved: false };
}
update(
state: PluginState,
value: unknown,
_delta?: unknown,
_allStates?: Record<string, unknown>
): PluginState {
console.log('First plugin updated with value:', value);
executionOrder.push('first-update');
pluginTracker.first.updated = true;
return {
...state,
value: String(value),
updated: true
};
}
resolve(state: PluginState, _allStates?: Record<string, unknown>): string {
console.log('First plugin resolved with value:', state.value);
executionOrder.push('first-resolve');
pluginTracker.first.resolved = true;
return state.value;
}
}
class SecondPlugin implements ResolverPlugin<PluginState> {
name = 'second';
dependencies: string[] = ['first'];
initialize(): PluginState {
console.log('Second plugin initialized');
executionOrder.push('second-init');
return { value: '', updated: false, resolved: false };
}
update(
state: PluginState,
value: unknown,
_delta?: unknown,
allStates?: Record<string, unknown>
): PluginState {
console.log('Second plugin updated with value:', value);
executionOrder.push('second-update');
pluginTracker.second.updated = true;
// Check if we have access to first plugin's state
const firstState = allStates?.first as PluginState | undefined;
if (firstState) {
executionOrder.push('second-has-first-state');
console.log('Second plugin has access to first plugin state:', firstState);
}
return {
...state,
value: `${value}-${firstState?.value || 'unknown'}`,
updated: true
};
}
resolve(state: PluginState, _allStates?: Record<string, unknown>): string {
console.log('Second plugin resolved with value:', state.value);
executionOrder.push('second-resolve');
pluginTracker.second.resolved = true;
return state.value;
}
}
// Create resolver with dependency order: first -> second
console.log('Creating resolver with plugins');
// Create resolver with test plugins first
const firstPlugin = new FirstPlugin();
const secondPlugin = new SecondPlugin();
const testResolver = new CustomResolver(lossless, {
first: firstPlugin,
second: secondPlugin
});
// Verify plugins are not yet initialized
expect(pluginTracker.first.updated).toBe(false);
expect(pluginTracker.second.updated).toBe(false);
// Verify the execution order array is empty before processing
expect(executionOrder).not.toContain('first-init');
expect(executionOrder).not.toContain('second-init');
expect(executionOrder).toHaveLength(0);
// Create and ingest test data
const delta = createDelta('test1', 'host1')
.withTimestamp(1000)
.setProperty('test1', 'first', 'first', 'prop1')
.setProperty('test1', 'second', 'second', 'prop2')
.buildV1();
lossless.ingestDelta(delta);
// Resolve the view
const result = testResolver.resolve();
// Verify the result
expect(result).toBeDefined();
if (!result) return;
const testEntity = result['test1'];
expect(testEntity).toBeDefined();
if (!testEntity) return;
// Check if properties exist
expect(testEntity.properties).toBeDefined();
// Check if plugins were resolved
expect(pluginTracker.first.resolved).toBe(true);
expect(pluginTracker.second.resolved).toBe(true);
// Check if second plugin has access to first plugin's state
expect(executionOrder).toContain('second-has-first-state');
// Check if first plugin was processed before second
const firstUpdateIndex = executionOrder.indexOf('first-update');
const secondUpdateIndex = executionOrder.indexOf('second-update');
expect(firstUpdateIndex).not.toBe(-1);
expect(secondUpdateIndex).not.toBe(-1);
expect(firstUpdateIndex).toBeLessThan(secondUpdateIndex);
// Verify initialization order (first should be initialized before second)
const firstInitIndex = executionOrder.indexOf('first-init');
const secondInitIndex = executionOrder.indexOf('second-init');
expect(firstInitIndex).not.toBe(-1);
expect(secondInitIndex).not.toBe(-1);
expect(firstInitIndex).toBeLessThan(secondInitIndex);
// Check if resolve was called in the right order
const firstResolveIndex = executionOrder.indexOf('first-resolve');
const secondResolveIndex = executionOrder.indexOf('second-resolve');
expect(firstResolveIndex).not.toBe(-1);
expect(secondResolveIndex).not.toBe(-1);
expect(firstResolveIndex).toBeLessThan(secondResolveIndex);
expect(firstInitIndex).toBeLessThan(secondInitIndex);
// Verify update order (first should be updated before second)
expect(firstUpdateIndex).toBeGreaterThanOrEqual(0);
expect(secondUpdateIndex).toBeGreaterThanOrEqual(0);
expect(firstUpdateIndex).toBeLessThan(secondUpdateIndex);
// Verify resolve order (first should be resolved before second)
expect(firstResolveIndex).toBeGreaterThanOrEqual(0);
expect(secondResolveIndex).toBeGreaterThanOrEqual(0);
expect(firstResolveIndex).toBeLessThan(secondResolveIndex);
// Check if second plugin could access first plugin's state
expect(executionOrder).toContain('second-has-first-state');
// Check resolved values if they exist
if (testEntity.properties.first) {
expect(testEntity.properties.first).toBe('first');
}
if (testEntity.properties.second) {
// Second plugin's value is 'second-<first plugin's value>'
expect(testEntity.properties.second).toBe('second-first');
}
});
test('should allow plugins to depend on other plugin states', () => {
// A plugin that applies a discount to a price
class DiscountedPricePlugin implements ResolverPlugin<{ price: number }> {
name = 'discounted-price';
initialize() {
return { price: 0 };
}
update(
currentState: { price: number },
newValue: PropertyTypes,
_delta: CollapsedDelta,
_allStates?: Record<string, unknown>
) {
if (typeof newValue === 'number') {
return { price: newValue };
}
return currentState;
}
resolve(
state: { price: number },
allStates?: Record<string, unknown>
): number | undefined {
// Get discount from another plugin's state
const discountState = allStates?.['discount'] as { value: number } | undefined;
if (discountState) {
return state.price * (1 - (discountState.value / 100));
}
return state.price;
}
}
// A simple discount plugin
class DiscountPlugin implements ResolverPlugin<{ value: number }> {
name = 'discount';
initialize() {
return { value: 0 };
}
update(
currentState: { value: number },
newValue: PropertyTypes,
_delta: CollapsedDelta,
_allStates?: Record<string, unknown>
) {
if (typeof newValue === 'number') {
return { value: newValue };
}
return currentState;
}
resolve(
state: { value: number },
_allStates?: Record<string, unknown>
): number {
return state.value;
}
}
// Set base price
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('product1', 'price', 100, 'products')
.buildV1()
);
// Set discount (20%)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('product1', 'discount', 20, 'products')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
price: new DiscountedPricePlugin(),
discount: new DiscountPlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['product1'].properties.price).toBe(80); // 100 - 20%
expect(result!['product1'].properties.discount).toBe(20);
});
});
describe('Custom Plugin Implementation', () => {
test('should work with custom plugin', () => {
// Custom plugin that counts the number of updates
class CountPlugin implements ResolverPlugin<{count: number}> {
name = 'count';
initialize() {
return {count: 0};
}
update(currentState: {count: number}, _newValue: PropertyTypes, _delta: CollapsedDelta) {
return {count: currentState.count + 1};
}
resolve(state: {count: number}): PropertyTypes {
return state.count;
}
}
// First update
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'updates', 'first', 'collection')
.buildV1()
);
// Second update
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'updates', 'second', 'collection')
.buildV1()
);
// Third update
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(3000)
.setProperty('entity1', 'updates', 'third', 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
updates: new CountPlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.updates).toBe(3);
});
test('should work with stateful custom plugin', () => {
// Custom plugin that calculates running average
class RunningAveragePlugin implements ResolverPlugin<{sum: number, count: number}> {
name = 'running-average';
initialize() {
return {sum: 0, count: 0};
}
update(currentState: {sum: number, count: number}, newValue: PropertyTypes, _delta: CollapsedDelta) {
if (typeof newValue === 'number') {
return {
sum: currentState.sum + newValue,
count: currentState.count + 1
};
}
return currentState;
}
resolve(state: {sum: number, count: number}): PropertyTypes {
return state.count > 0 ? state.sum / state.count : 0;
}
}
// First score (10)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'score', 10, 'collection')
.buildV1()
);
// Second score (20)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'score', 20, 'collection')
.buildV1()
);
// Third score (30)
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(3000)
.setProperty('entity1', 'score', 30, 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
score: new RunningAveragePlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['entity1'].properties.score).toBe(20); // (10 + 20 + 30) / 3
});
});
describe('Edge Cases', () => {
test('should handle empty delta sets', () => {
const resolver = new CustomResolver(lossless, {
name: new LastWriteWinsPlugin()
});
const result = resolver.resolve();
expect(result).toBeDefined();
expect(Object.keys(result!)).toHaveLength(0);
});
test('should handle non-matching property types gracefully', () => {
// Add string value to numeric plugin
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'score', 'not_a_number', 'collection')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
score: new MinPlugin() // Expects numeric values
});
const result = resolver.resolve();
expect(result).toBeDefined();
// The entity might not be present in the result if no properties were resolved
if (result!['entity1']) {
expect(result!['entity1'].properties).toBeDefined();
expect(result!['entity1'].properties).not.toHaveProperty('score');
}
});
});
});

59
__tests__/unit/views/resolvers/custom-resolvers/builtin-plugins/concatenation.test.ts
View File

@ -1,59 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { ConcatenationPlugin } from '@src/views/resolvers/custom-resolvers';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
describe('ConcatenationPlugin', () => {
test('should join string values chronologically', async () => {
// Define test data
const entityId = 'entity1';
// Run test & verify results
const result = await testResolverWithPlugins({
entityId,
plugins: {
tags: new ConcatenationPlugin()
},
deltas: [
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'tags', 'red', 'color1')
.buildV1(),
createTestDelta('user1', 'host1')
.withTimestamp(3000)
.setProperty(entityId, 'tags', 'blue', 'color2')
.buildV1(),
createTestDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty(entityId, 'tags', 'green', 'color3')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result?.properties.tags).toBe('red green blue');
});
test('should handle empty values', async () => {
// Define test data
const entityId = 'entity1';
// Run test & verify results
const result = await testResolverWithPlugins({
entityId,
plugins: {
tags: new ConcatenationPlugin()
},
deltas: [
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'tags', null, 'tag1')
.buildV1(),
createTestDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty(entityId, 'tags', 'blue', 'tag2')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result?.properties.tags).toBe('blue');
});
});

57
__tests__/unit/views/resolvers/custom-resolvers/builtin-plugins/first-write-wins.test.ts
View File

@ -1,57 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { FirstWriteWinsPlugin } from '@src/views/resolvers/custom-resolvers';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
describe('FirstWriteWinsPlugin', () => {
test('should resolve to earliest value by timestamp', async () => {
// Arrange
const entityId = 'entity1';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
name: new FirstWriteWinsPlugin()
},
deltas: [
// Later delta (should be ignored by FirstWriteWins)
createTestDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty(entityId, 'name', 'second', 'collection')
.buildV1(),
// Earlier delta (should win with FirstWriteWins)
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'name', 'first', 'collection')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result.properties.name).toBe('first');
});
test('should handle concurrent updates with same timestamp', async () => {
// Arrange
const entityId = 'entity1';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
status: new FirstWriteWinsPlugin()
},
deltas: [
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'status', 'active', 'collection')
.buildV1(),
createTestDelta('user2', 'host2')
.withTimestamp(1000)
.setProperty(entityId, 'status', 'inactive', 'collection')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result.properties.status).toBe('active');
});
});

58
__tests__/unit/views/resolvers/custom-resolvers/builtin-plugins/last-write-wins.test.ts
View File

@ -1,58 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { LastWriteWinsPlugin } from '@src/views/resolvers/custom-resolvers';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
describe('LastWriteWinsPlugin', () => {
test('should resolve to most recent value by timestamp', async () => {
// Arrange
const entityId = 'entity1';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
name: new LastWriteWinsPlugin()
},
deltas: [
// First delta with earlier timestamp
createTestDelta()
.withTimestamp(1000)
.setProperty(entityId, 'name', 'first', 'collection')
.buildV1(),
// Second delta with later timestamp (should win)
createTestDelta()
.withTimestamp(2000)
.setProperty(entityId, 'name', 'second', 'collection')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result?.properties.name).toBe('second');
});
test('should handle concurrent updates with same timestamp', async () => {
// Arrange
const entityId = 'entity1';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
status: new LastWriteWinsPlugin()
},
deltas: [
// Two deltas with same timestamp
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'status', 'active', 'collection')
.buildV1(),
createTestDelta('user2', 'host2')
.withTimestamp(1000)
.setProperty(entityId, 'status', 'inactive', 'collection')
.buildV1()
],
});
expect(result).toBeDefined();
expect(['active', 'inactive']).toContain(result?.properties.status);
});
});

81
__tests__/unit/views/resolvers/custom-resolvers/builtin-plugins/majority-vote.test.ts
View File

@ -1,81 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { MajorityVotePlugin } from '@src/views/resolvers/custom-resolvers';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
describe('MajorityVotePlugin', () => {
test('should resolve to value with majority votes', async () => {
// Arrange
const entityId = 'poll1';
// Create deltas for testing
const deltas = [];
// Add three votes for 'yes'
for (let i = 0; i < 3; i++) {
deltas.push(
createTestDelta(`user${i}`, 'host1')
.withTimestamp(1000 + i)
.setProperty(entityId, 'result', 'yes', 'polls')
.buildV1()
);
}
// Add two votes for 'no'
for (let i = 0; i < 2; i++) {
deltas.push(
createTestDelta(`user${i + 3}`, 'host1')
.withTimestamp(2000 + i)
.setProperty(entityId, 'result', 'no', 'polls')
.buildV1()
);
}
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
result: new MajorityVotePlugin()
},
deltas,
});
expect(result).toBeDefined();
expect(result.properties.result).toBe('yes');
});
test('should handle tie by returning the first value with the maximum count', async () => {
// Arrange
const entityId = 'tie1';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
result: new MajorityVotePlugin()
},
deltas: [
// Two votes for 'no' (added first)
createTestDelta('user3', 'host1')
.withTimestamp(2000)
.setProperty(entityId, 'result', 'no', 'polls')
.buildV1(),
createTestDelta('user4', 'host1')
.withTimestamp(2500)
.setProperty(entityId, 'result', 'no', 'polls')
.buildV1(),
// Two votes for 'yes' (added later, but the implementation doesn't track order)
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'result', 'yes', 'polls')
.buildV1(),
createTestDelta('user2', 'host1')
.withTimestamp(1500)
.setProperty(entityId, 'result', 'yes', 'polls')
.buildV1()
]
});
expect(result).toBeDefined();
// The current implementation will return the first value it encounters with the maximum count
// Since we can't guarantee the order of Map iteration, we'll just check that we get a result
expect(['yes', 'no']).toContain(result.properties.result);
});
});

60
__tests__/unit/views/resolvers/custom-resolvers/builtin-plugins/max.test.ts
View File

@ -1,60 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { MaxPlugin } from '@src/views/resolvers/custom-resolvers';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
describe('MaxPlugin', () => {
test('should resolve to the maximum numeric value', async () => {
// Arrange
const entityId = 'sensor1';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
temperature: new MaxPlugin()
},
deltas: [
// Add multiple values
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'temperature', 25, 'readings')
.buildV1(),
createTestDelta('user2', 'host1')
.withTimestamp(2000)
.setProperty(entityId, 'temperature', 22, 'readings')
.buildV1(),
createTestDelta('user3', 'host1')
.withTimestamp(3000)
.setProperty(entityId, 'temperature', 27, 'readings')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result.properties.temperature).toBe(27);
});
test('should handle negative numbers', async () => {
// Arrange
const entityId = 'sensor2';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
value: new MaxPlugin()
},
deltas: [
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'value', -5, 'readings')
.buildV1(),
createTestDelta('user2', 'host1')
.withTimestamp(2000)
.setProperty(entityId, 'value', -10, 'readings')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result.properties.value).toBe(-5);
});
});

60
__tests__/unit/views/resolvers/custom-resolvers/builtin-plugins/min.test.ts
View File

@ -1,60 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { MinPlugin } from '@src/views/resolvers/custom-resolvers';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
describe('MinPlugin', () => {
test('should resolve to the minimum numeric value', async () => {
// Arrange
const entityId = 'sensor1';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
temperature: new MinPlugin()
},
deltas: [
// Add multiple values
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'temperature', 25, 'readings')
.buildV1(),
createTestDelta('user2', 'host1')
.withTimestamp(2000)
.setProperty(entityId, 'temperature', 22, 'readings')
.buildV1(),
createTestDelta('user3', 'host1')
.withTimestamp(3000)
.setProperty(entityId, 'temperature', 27, 'readings')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result?.properties.temperature).toBe(22);
});
test('should handle negative numbers', async () => {
// Arrange
const entityId = 'sensor2';
// Act & Assert
const result = await testResolverWithPlugins({
entityId,
plugins: {
value: new MinPlugin()
},
deltas: [
createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty(entityId, 'value', -5, 'readings')
.buildV1(),
createTestDelta('user2', 'host1')
.withTimestamp(2000)
.setProperty(entityId, 'value', -10, 'readings')
.buildV1()
],
});
expect(result).toBeDefined();
expect(result?.properties.value).toBe(-10);
});
});

77
__tests__/unit/views/resolvers/custom-resolvers/dependency/basic-dependencies.test.ts
View File

@ -1,77 +0,0 @@
import { describe, test, expect, beforeEach } from '@jest/globals';
import { RhizomeNode, Lossless, createDelta } from '@src';
import { CollapsedDelta } from '@src/views/lossless';
import { CustomResolver, ResolverPlugin } from '@src/views/resolvers/custom-resolvers';
type PropertyTypes = string | number | boolean | null;
describe('Basic Dependency Resolution', () => {
let node: RhizomeNode;
let lossless: Lossless;
beforeEach(() => {
node = new RhizomeNode();
lossless = new Lossless(node);
});
test('should resolve dependencies in correct order', () => {
// Define a simple plugin that depends on another
class FirstPlugin implements ResolverPlugin<{ value: string }, string> {
readonly dependencies = [] as const;
initialize() {
return { value: '' };
}
update(_currentState: { value: string }, newValue: PropertyTypes) {
return { value: String(newValue) };
}
resolve(state: { value: string }) {
return state.value.toUpperCase();
}
}
class SecondPlugin implements ResolverPlugin<{ value: string }, string> {
readonly dependencies = ['first'] as const;
initialize() {
return { value: '' };
}
update(_currentState: { value: string }, newValue: PropertyTypes, _delta: CollapsedDelta, dependencies: { first: string }) {
return { value: `${dependencies.first}_${newValue}` };
}
resolve(state: { value: string }) {
return state.value;
}
}
const resolver = new CustomResolver(lossless, {
first: new FirstPlugin(),
second: new SecondPlugin()
});
// Add some data
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('test1', 'first', 'hello', 'test')
.buildV1()
);
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('test1', 'second', 'world', 'test')
.buildV1()
);
const result = resolver.resolve();
expect(result).toBeDefined();
expect(result!['test1'].properties.first).toBe('HELLO');
expect(result!['test1'].properties.second).toBe('HELLO_world');
});
});

94
__tests__/unit/views/resolvers/custom-resolvers/dependency/circular-dependencies.test.ts
View File

@ -1,94 +0,0 @@
import { describe, test, expect, beforeEach } from '@jest/globals';
import { RhizomeNode, Lossless } from '@src';
import { CollapsedDelta } from '@src/views/lossless';
import { CustomResolver, ResolverPlugin } from '@src/views/resolvers/custom-resolvers';
type PropertyTypes = string | number | boolean | null;
describe('Circular Dependency Detection', () => {
let node: RhizomeNode;
let lossless: Lossless;
beforeEach(() => {
node = new RhizomeNode();
lossless = new Lossless(node);
});
test('should detect circular dependencies', () => {
// PluginA depends on PluginB
class PluginA implements ResolverPlugin<{ value: string }, string> {
readonly dependencies = ['b'] as const;
initialize() {
return { value: '' };
}
update(currentState: { value: string }, newValue: PropertyTypes, _delta: CollapsedDelta, _dependencies: { b: string }) {
return { value: String(newValue) };
}
resolve(_state: { value: string }) {
return 'a';
}
}
// PluginB depends on PluginA (circular dependency)
class PluginB implements ResolverPlugin<{ value: string }, string> {
readonly dependencies = ['a'] as const;
initialize() {
return { value: '' };
}
update(_currentState: { value: string }, newValue: PropertyTypes, _delta: CollapsedDelta, _dependencies: { a: string }) {
return { value: String(newValue) };
}
resolve(_state: { value: string }) {
return 'b';
}
}
// Should throw an error when circular dependencies are detected
expect(() => {
new CustomResolver(lossless, {
'a': new PluginA(),
'b': new PluginB()
});
}).toThrow('Circular dependency detected in plugin dependencies');
});
test('should detect longer circular dependency chains', () => {
class PluginA implements ResolverPlugin<{ value: string }, string> {
readonly dependencies = ['c'] as const;
initialize() { return { value: '' }; }
update() { return { value: '' }; }
resolve() { return 'a'; }
}
class PluginB implements ResolverPlugin<{ value: string }, string> {
readonly dependencies = ['a'] as const;
initialize() { return { value: '' }; }
update() { return { value: '' }; }
resolve() { return 'b'; }
}
class PluginC implements ResolverPlugin<{ value: string }, string> {
readonly dependencies = ['b'] as const;
initialize() { return { value: '' }; }
update() { return { value: '' }; }
resolve() { return 'c'; }
}
// Should detect the circular dependency: a -> c -> b -> a
expect(() => {
new CustomResolver(lossless, {
'a': new PluginA(),
'b': new PluginB(),
'c': new PluginC()
});
}).toThrow('Circular dependency detected in plugin dependencies');
});
});

218
__tests__/unit/views/resolvers/custom-resolvers/edge-cases/edge-cases.test.ts
View File

@ -1,218 +0,0 @@
import { describe, test, expect, beforeEach } from '@jest/globals';
import { RhizomeNode, Lossless, createDelta, CollapsedDelta } from '@src';
import {
CustomResolver,
DependencyStates,
ResolverPlugin
} from '@src/views/resolvers/custom-resolvers';
import { PropertyTypes } from '@src/core/types';
describe('Edge Cases', () => {
let node: RhizomeNode;
let lossless: Lossless;
beforeEach(() => {
node = new RhizomeNode();
lossless = new Lossless(node);
});
test('should handle null and undefined values', () => {
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('test1', 'value', null, 'test')
.buildV1()
);
// Use null instead of undefined as it's a valid PropertyType
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('test1', 'value', null, 'test')
.buildV1()
);
// Create a type-safe plugin that handles null/undefined values
class NullSafeLastWriteWinsPlugin implements ResolverPlugin<{ value: PropertyTypes | null, timestamp: number }, never> {
readonly dependencies = [] as const;
initialize() {
return { value: null, timestamp: 0 };
}
update(
currentState: { value: PropertyTypes | null, timestamp: number },
newValue: PropertyTypes,
delta: CollapsedDelta,
_dependencies: DependencyStates
) {
if (delta.timeCreated > currentState.timestamp) {
return { value: newValue, timestamp: delta.timeCreated };
}
return currentState;
}
resolve(
state: { value: PropertyTypes | null, timestamp: number },
_dependencies: DependencyStates
): PropertyTypes | undefined {
return state.value ?? undefined;
}
}
const resolver = new CustomResolver(lossless, {
value: new NullSafeLastWriteWinsPlugin()
});
const results = resolver.resolve() || [];
expect(Array.isArray(results)).toBe(true);
const test1 = results.find(r => r.id === 'test1');
expect(test1).toBeDefined();
expect(test1?.properties.value).toBeUndefined();
});
test('should handle concurrent updates with same timestamp', () => {
// Two updates with the same timestamp
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('test2', 'value', 'first', 'test')
.buildV1()
);
lossless.ingestDelta(
createDelta('user2', 'host2')
.withTimestamp(1000) // Same timestamp
.setProperty('test2', 'value', 'second', 'test')
.buildV1()
);
// Custom plugin that handles concurrent updates with the same timestamp
class ConcurrentUpdatePlugin implements ResolverPlugin<{ value: PropertyTypes, timestamp: number }, never> {
readonly dependencies = [] as const;
initialize() {
return { value: '', timestamp: 0 };
}
update(
currentState: { value: PropertyTypes, timestamp: number },
newValue: PropertyTypes,
delta: CollapsedDelta,
_dependencies: DependencyStates
) {
if (delta.timeCreated > currentState.timestamp) {
return { value: newValue, timestamp: delta.timeCreated };
} else if (delta.timeCreated === currentState.timestamp) {
// For concurrent updates, prefer the one with the lexicographically smaller value
const currentVal = String(currentState.value);
const newVal = String(newValue);
return newVal < currentVal
? { value: newValue, timestamp: delta.timeCreated }
: currentState;
}
return currentState;
}
resolve(state: { value: PropertyTypes, timestamp: number }) {
return state.value;
}
}
const resolver = new CustomResolver(lossless, {
value: new ConcurrentUpdatePlugin()
});
const results = resolver.resolve() || [];
expect(Array.isArray(results)).toBe(true);
const test2 = results.find(r => r.id === 'test2');
expect(test2).toBeDefined();
// Should pick one of the values deterministically
expect(test2?.properties.value).toBe('first');
});
test('should handle very large numbers of updates', () => {
// Add 1000 updates
for (let i = 0; i < 1000; i++) {
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000 + i)
.setProperty('test3', 'counter', i, 'test')
.buildV1()
);
}
// Plugin that handles large numbers of updates efficiently
class CounterPlugin implements ResolverPlugin<{ count: number }, never> {
readonly dependencies = [] as const;
initialize() {
return { count: 0 };
}
update(
currentState: { count: number },
_newValue: PropertyTypes,
_delta: CollapsedDelta,
_dependencies: DependencyStates
) {
return { count: currentState.count + 1 };
}
resolve(
state: { count: number },
_dependencies: DependencyStates
): number {
return state.count;
}
}
const resolver = new CustomResolver(lossless, {
counter: new CounterPlugin()
});
const results = resolver.resolve() || [];
expect(Array.isArray(results)).toBe(true);
const test3 = results.find(r => r.id === 'test3');
expect(test3).toBeDefined();
// Should handle large numbers of updates efficiently
expect(test3?.properties.counter).toBe(1000); // Should count all 1000 updates
});
test('should handle missing properties gracefully', () => {
// No deltas added - should handle empty state
// Plugin that handles missing properties gracefully
class MissingPropertyPlugin implements ResolverPlugin<{ initialized: boolean }, never> {
private _initialized = false;
readonly dependencies = [] as const;
initialize() {
this._initialized = true;
return { initialized: true };
}
update(
currentState: { initialized: boolean },
_newValue: PropertyTypes,
_delta: CollapsedDelta,
_dependencies: DependencyStates
) {
return currentState;
}
resolve(
_state: { initialized: boolean },
_dependencies: DependencyStates
): boolean {
return this._initialized;
}
}
const resolver = new CustomResolver(lossless, {
missing: new MissingPropertyPlugin()
});
const result = resolver.resolve();
expect(result).toEqual({});
});
});

140
__tests__/unit/views/resolvers/custom-resolvers/integration/multiple-plugins.test.ts
View File

@ -1,140 +0,0 @@
import { PropertyID } from '@src/core/types';
import { describe, test, expect, beforeEach } from '@jest/globals';
import { RhizomeNode, Lossless, createDelta } from '@src';
import {
CustomResolver,
LastWriteWinsPlugin,
ConcatenationPlugin,
MaxPlugin,
MinPlugin,
ResolverPlugin
} from '@src/views/resolvers/custom-resolvers';
// A simple plugin that depends on other plugins
class AveragePlugin<Targets extends PropertyID> implements ResolverPlugin<{ initialized: boolean }, Targets> {
readonly dependencies: Targets[] = [];
constructor(...targets: Targets[]) {
if (targets.length !== 2) {
throw new Error('This AveragePlugin requires exactly two targets');
}
this.dependencies = targets;
}
initialize(): { initialized: boolean } {
return { initialized: true };
}
update(): { initialized: boolean } {
// No state updates needed for this plugin
return { initialized: true };
}
resolve(
_state: { initialized: boolean },
dependencies: { [K in Targets]: number | undefined }
): number | undefined {
const [depId1, depId2] = this.dependencies;
const min = dependencies[depId1];
const max = dependencies[depId2];
if (min === undefined || max === undefined) {
return undefined;
}
return (min + max) / 2;
}
}
describe('Multiple Plugins Integration', () => {
let node: RhizomeNode;
let lossless: Lossless;
beforeEach(() => {
node = new RhizomeNode();
lossless = new Lossless(node);
});
test('should handle multiple plugins with dependencies', () => {
const resolver = new CustomResolver(lossless, {
temperature: new LastWriteWinsPlugin(),
maxTemp: new MaxPlugin('temperature'),
minTemp: new MinPlugin('temperature'),
avgTemp: new AveragePlugin('minTemp', 'maxTemp')
});
// Add some temperature readings
const readings = [22, 25, 18, 30, 20];
readings.forEach((temp, index) => {
lossless.ingestDelta(
createDelta('sensor1', 'host1')
.withTimestamp(1000 + index * 1000)
.setProperty('room1', 'temperature', temp, 'sensors')
.buildV1()
);
});
const results = resolver.resolve();
expect(results).toBeDefined();
const room = results!['room1'];
expect(room).toBeDefined();
// Verify all plugins worked together
expect(room?.properties.temperature).toBe(20); // Last write
expect(room?.properties.maxTemp).toBe(30); // Max value
expect(room?.properties.minTemp).toBe(18); // Min value
expect(room?.properties.avgTemp).toBe(24); // (18 + 30) / 2
});
test('should handle multiple entities with different plugins', () => {
const resolver = new CustomResolver(lossless, {
name: new LastWriteWinsPlugin(),
tags: new ConcatenationPlugin(),
score: new MaxPlugin('score')
});
// Add data for entity1
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'name', 'Test Entity', 'test')
.setProperty('entity1', 'tags', 'tag1', 'test')
.buildV1()
);
// Add more tags to entity1
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity1', 'tags', 'tag2', 'test')
.buildV1()
);
// Add data for entity2
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity2', 'score', 85, 'test')
.buildV1()
);
// Update score for entity2
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('entity2', 'score', 90, 'test')
.buildV1()
);
const results = resolver.resolve();
expect(results).toBeDefined();
const entity1 = results!['entity1'];
expect(entity1).toBeDefined();
expect(entity1?.properties.name).toBe('Test Entity');
expect(entity1?.properties.tags).toEqual(['tag1', 'tag2']);
const entity2 = results!['entity2'];
expect(entity2).toBeDefined();
expect(entity2?.properties.score).toBe(90);
});
});

139
__tests__/unit/views/resolvers/custom-resolvers/lifecycle/plugin-lifecycle.test.ts
View File

@ -1,139 +0,0 @@
import { describe, test, expect, beforeEach } from '@jest/globals';
import { RhizomeNode, Lossless, createDelta, CollapsedDelta } from '@src';
import {
CustomResolver,
ResolverPlugin,
DependencyStates
} from '@src/views/resolvers/custom-resolvers';
import { PropertyTypes } from '@src/core/types';
// A simple plugin for testing lifecycle methods
class LifecycleTestPlugin implements ResolverPlugin<LifecycleTestState> {
readonly dependencies = [] as const;
private initialState: LifecycleTestState = {
initialized: true,
updated: false,
resolved: false
};
initialize(): LifecycleTestState {
return { ...this.initialState };
}
update(
currentState: LifecycleTestState,
_newValue: PropertyTypes,
_delta: CollapsedDelta,
_dependencies: DependencyStates
): LifecycleTestState {
return { ...currentState, updated: true };
}
resolve(
state: LifecycleTestState,
_dependencies: DependencyStates
): PropertyTypes {
// Return a valid PropertyTypes value (string, number, boolean, or null)
// We'll use a JSON string representation of the state
return JSON.stringify({ ...state, resolved: true });
}
}
type LifecycleTestState = {
initialized: boolean;
updated: boolean;
resolved: boolean;
};
describe('Plugin Lifecycle', () => {
let node: RhizomeNode;
let lossless: Lossless;
beforeEach(() => {
node = new RhizomeNode();
lossless = new Lossless(node);
});
test('should call initialize, update, and resolve in order', () => {
// Add some data
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('test1', 'test', 'value1', 'test')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
test: new LifecycleTestPlugin()
});
const results = resolver.resolve() || [];
expect(Array.isArray(results)).toBe(true);
const entity = results.find(r => r.id === 'test1');
expect(entity).toBeDefined();
// Verify all lifecycle methods were called in the correct order
const testProperty = entity?.properties.test;
expect(testProperty).toBeDefined();
// The resolved value should be the return value from resolve() which is a JSON string
const parsed = JSON.parse(testProperty as string);
expect(parsed).toEqual({
initialized: true,
updated: true,
resolved: true
});
});
test('should handle multiple updates correctly', () => {
// First update
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('test2', 'test', 'value1', 'test')
.buildV1()
);
// Second update
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(2000)
.setProperty('test2', 'test', 'value2', 'test')
.buildV1()
);
const resolver = new CustomResolver(lossless, {
test: new LifecycleTestPlugin()
});
const results = resolver.resolve() || [];
expect(Array.isArray(results)).toBe(true);
const entity = results.find(r => r.id === 'test2');
expect(entity).toBeDefined();
// Verify state after multiple updates
const testProperty = entity?.properties.test;
expect(testProperty).toBeDefined();
// The resolved value should be the return value from resolve() which is a JSON string
const parsed = JSON.parse(testProperty as string);
expect(parsed).toEqual({
initialized: true,
updated: true, // Should be true from the last update
resolved: true
});
});
test('should handle empty state', () => {
const resolver = new CustomResolver(lossless, {
test: new LifecycleTestPlugin()
});
const results = resolver.resolve();
expect(Array.isArray(results)).toBe(true);
expect(results).toHaveLength(0);
});
});

109
__tests__/unit/views/resolvers/custom-resolvers/plugins/count-plugin.test.ts
View File

@ -1,109 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { ResolverPlugin, DependencyStates } from '@src/views/resolvers/custom-resolvers';
import { PropertyTypes } from '@src/core/types';
import type { CollapsedDelta } from '@src/views/lossless';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
class CountPlugin implements ResolverPlugin<{ count: number }, never> {
readonly dependencies = [] as const;
initialize() {
return { count: 0 };
}
update(
currentState: { count: number },
_newValue: PropertyTypes,
_delta: CollapsedDelta,
_dependencies: DependencyStates
) {
return { count: currentState.count + 1 };
}
resolve(
state: { count: number },
_dependencies: DependencyStates
): number {
return state.count;
}
}
describe('CountPlugin', () => {
test('should count the number of updates', async () => {
// Arrange & Act
const entityId = 'counter1';
await testResolverWithPlugins({
entityId,
plugins: {
count: new CountPlugin()
},
deltas: [
createTestDelta()
.withTimestamp(1000)
.setProperty(entityId, 'count', 'value1', 'test')
.buildV1(),
createTestDelta()
.withTimestamp(2000)
.setProperty(entityId, 'count', 'value2', 'test')
.buildV1(),
createTestDelta()
.withTimestamp(3000)
.setProperty(entityId, 'count', 'value3', 'test')
.buildV1()
],
expectedResult: (result) => {
// Assert
expect(result).toBeDefined();
expect(result.properties.count).toBe(3);
}
});
});
test('should handle multiple entities independently', async () => {
// Arrange
const counter1Deltas = [
createTestDelta()
.withTimestamp(1000)
.setProperty('counter1', 'count', 'value1', 'test')
.buildV1(),
createTestDelta()
.withTimestamp(2000)
.setProperty('counter1', 'count', 'value2', 'test')
.buildV1()
];
const counter2Deltas = [
createTestDelta()
.withTimestamp(1000)
.setProperty('counter2', 'count', 'value1', 'test')
.buildV1()
];
// Act & Assert - Test counter1
await testResolverWithPlugins({
entityId: 'counter1',
plugins: {
count: new CountPlugin()
},
deltas: counter1Deltas,
expectedResult: (result) => {
expect(result).toBeDefined();
expect(result.properties.count).toBe(2);
}
});
// Act & Assert - Test counter2
await testResolverWithPlugins({
entityId: 'counter2',
plugins: {
count: new CountPlugin()
},
deltas: counter2Deltas,
expectedResult: (result) => {
expect(result).toBeDefined();
expect(result.properties.count).toBe(1);
}
});
});
});

173
__tests__/unit/views/resolvers/custom-resolvers/plugins/discount-plugins.test.ts
View File

@ -1,173 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { ResolverPlugin, DependencyStates } from '@src/views/resolvers/custom-resolvers';
import { PropertyTypes } from '@src/core/types';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
import Debug from 'debug';
const debug = Debug('rz:test:discount-plugins');
// Mock plugins for testing
class DiscountPlugin implements ResolverPlugin<number, never> {
readonly name = 'discount' as const;
readonly dependencies = [] as const;
initialize() {
return 0;
}
update(
_currentState: number,
newValue: PropertyTypes,
) {
const numValue = typeof newValue === 'number' ? newValue : 0;
const clampedValue = Math.min(100, Math.max(0, numValue)); // Clamp between 0-100
debug(`DiscountPlugin: updated discount to ${clampedValue}`);
return clampedValue;
}
resolve( state: number ): number {
return state;
}
}
class DiscountedPricePlugin implements ResolverPlugin<number | null, 'discount'> {
readonly name = 'price' as const;
readonly dependencies = ['discount'] as const;
initialize() {
return null;
}
update(
_currentState: number | null,
newValue: PropertyTypes,
) {
const numValue = typeof newValue === 'number' ? newValue : 0;
debug(`DiscountedPricePlugin: updated price to ${numValue}`);
return numValue;
}
resolve(
state: number | null,
dependencies: DependencyStates
): number | null {
if (state === null) {
return null;
}
// Ensure discount is a number and default to 0 if undefined
const discount = typeof dependencies.discount === 'number' ? dependencies.discount : 0;
const discountMultiplier = (100 - discount) / 100;
return state * discountMultiplier;
}
}
describe('Discount and DiscountedPrice Plugins', () => {
test('should apply discount to price', async () => {
// Arrange
const entityId = 'product1';
// Act
const result = await testResolverWithPlugins({
entityId,
plugins: {
price: new DiscountedPricePlugin(),
discount: new DiscountPlugin()
},
deltas: [
// Set base price
createTestDelta()
.withTimestamp(1000)
.setProperty(entityId, 'price', 100, 'product')
.buildV1(),
// Set discount (20%)
createTestDelta()
.withTimestamp(2000)
.setProperty(entityId, 'discount', 20, 'product')
.buildV1()
],
});
// Assert
expect(result).toBeDefined();
expect(result?.properties?.price).toBe(80); // 100 * 0.8 = 80
});
test('should handle zero discount', async () => {
// Arrange
const entityId = 'product1';
// Act
const result = await testResolverWithPlugins({
entityId,
plugins: {
price: new DiscountedPricePlugin(),
discount: new DiscountPlugin()
},
deltas: [
// Set base price
createTestDelta()
.withTimestamp(1000)
.setProperty(entityId, 'price', 100, 'products')
.buildV1(),
// Set discount to 0
createTestDelta()
.withTimestamp(2000)
.setProperty(entityId, 'discount', 0, 'products')
.buildV1()
],
});
// Assert
expect(result).toBeDefined();
expect(result?.properties?.price).toBe(100); // 100 * 1.0 = 100
});
test('should handle 100% discount', async () => {
// Arrange
const entityId = 'product1';
// Act
const result = await testResolverWithPlugins({
entityId,
plugins: {
price: new DiscountedPricePlugin(),
discount: new DiscountPlugin()
},
deltas: [
// Set base price
createTestDelta()
.withTimestamp(1000)
.setProperty(entityId, 'price', 100, 'products')
.buildV1(),
// Set discount to 100%
createTestDelta()
.withTimestamp(2000)
.setProperty(entityId, 'discount', 100, 'products')
.buildV1()
],
});
// Assert
expect(result).toBeDefined();
expect(result?.properties.price).toBe(0); // 100 * 0.0 = 0
});
test('should handle missing discount plugin', async () => {
// Arrange
const entityId = 'product1';
// Act
await expect(
testResolverWithPlugins({
entityId,
plugins: {
price: new DiscountedPricePlugin()
// No discount plugin provided
},
deltas: [
// Set base price
createTestDelta()
.withTimestamp(1000)
.setProperty(entityId, 'price', 100, 'products')
.buildV1()
]
})).rejects.toThrowError('Dependency discount not found for plugin price');
});
});

90
__tests__/unit/views/resolvers/custom-resolvers/plugins/running-average.test.ts
View File

@ -1,90 +0,0 @@
import { describe, test, expect } from '@jest/globals';
import { RunningAveragePlugin } from '@src/views/resolvers/custom-resolvers/plugins/running-average.plugin';
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
describe('RunningAveragePlugin', () => {
test('should calculate running average of numeric values', async () => {
// Arrange & Act
const entityId = 'player1';
await testResolverWithPlugins({
entityId,
plugins: {
score: new RunningAveragePlugin()
},
deltas: [
// First score (10)
createTestDelta()
.withTimestamp(1000)
.setProperty(entityId, 'score', 10, 'game')
.buildV1(),
// Second score (20)
createTestDelta()
.withTimestamp(2000)
.setProperty(entityId, 'score', 20, 'game')
.buildV1(),
// Third score (30)
createTestDelta()
.withTimestamp(3000)
.setProperty(entityId, 'score', 30, 'game')
.buildV1()
],
expectedResult: (result) => {
// Assert
expect(result).toBeDefined();
expect(result.properties.score).toBe(20); // (10 + 20 + 30) / 3 = 20
}
});
});
test('should handle non-numeric values gracefully', async () => {
// Arrange & Act
const entityId = 'test1';
await testResolverWithPlugins({
entityId,
plugins: {
value: new RunningAveragePlugin()
},
deltas: [
createTestDelta()
.withTimestamp(1000)
.setProperty(entityId, 'value', 'not a number', 'test')
.buildV1(),
createTestDelta()
.withTimestamp(2000)
.setProperty(entityId, 'value', 10, 'test')
.buildV1()
],
expectedResult: (result) => {
// Assert
expect(result).toBeDefined();
// First value is treated as 0, second as 10, average is (0 + 10) / 2 = 5
expect(result.properties.value).toBe(5);
}
});
});
test('should handle empty state', async () => {
// Arrange & Act
const entityId = 'non-existent';
let error: Error | undefined;
try {
await testResolverWithPlugins({
entityId,
plugins: {
value: new RunningAveragePlugin()
},
deltas: [],
expectedResult: () => {}
});
} catch (err) {
error = err as Error;
}
// Assert - The helper should throw when entity is not found
expect(error).toBeDefined();
expect(error?.message).toContain('No view found for entity non-existent');
});
});

131
__tests__/unit/views/resolvers/custom-resolvers/resolver.test.ts
View File

@ -1,131 +0,0 @@
import { describe, test, expect, beforeEach } from '@jest/globals';
import { RhizomeNode } from '@src';
import { Lossless } from '@src/views/lossless';
import { CustomResolver } from '@src/views/resolvers/custom-resolvers';
import { ResolverPlugin } from '@src/views/resolvers/custom-resolvers/plugin';
// import Debug from 'debug';
// const debug = Debug('rz:test:resolver');
// Mock plugins for testing
class TestPlugin implements ResolverPlugin<unknown, string> {
name: string;
dependencies: readonly string[];
constructor(name: string, dependencies: string[] = []) {
this.name = name;
this.dependencies = dependencies;
}
initialize() { return {}; }
update() { return {}; }
resolve() { return 'test'; }
}
describe('CustomResolver', () => {
let node: RhizomeNode;
let lossless: Lossless;
beforeEach(() => {
node = new RhizomeNode();
lossless = new Lossless(node);
});
describe('buildDependencyGraph', () => {
test('should build a simple dependency graph', () => {
// Arrange
const plugins = {
a: new TestPlugin('a'),
b: new TestPlugin('b', ['a']), // b depends on a
c: new TestPlugin('c', ['b']) // c depends on b
};
// Act
const resolver = new CustomResolver(lossless, plugins);
const graph = resolver.dependencyGraph;
// Assert
expect(graph.get('a')).toBeDefined();
expect(graph.get('b')).toBeDefined();
expect(graph.get('c')).toBeDefined();
// Check dependencies
expect(Array.from(graph.get('a') || [])).toContain('b'); // a -> b
expect(Array.from(graph.get('b') || [])).toContain('c'); // b -> c
});
test('should handle plugins with same basename but different keys', () => {
// Arrange
const plugins = {
'plugin:a': new TestPlugin('a'),
'plugin:b': new TestPlugin('b', ['a']), // depends on a
'another:b': new TestPlugin('b', ['a']) // same basename, different key
};
// Act
const resolver = new CustomResolver(lossless, plugins);
// Access private method for testing
const graph = resolver.dependencyGraph;
// Assert
expect(graph.get('a')).toBeDefined();
expect(graph.get('b')).toBeDefined();
// Both 'plugin:b' and 'another:b' should be in the graph as 'b'
expect(Array.from(graph.get('a') || [])).toContain('b');
});
test('should throw error for missing dependency', () => {
// Arrange
const plugins = {
a: new TestPlugin('a', ['nonexistent']) // depends on non-existent plugin
};
// Act & Assert
expect(() => {
new CustomResolver(lossless, plugins);
}).toThrow('Dependency nonexistent not found for plugin a');
});
test('should handle plugins with no dependencies', () => {
// Arrange
const plugins = {
a: new TestPlugin('a'),
b: new TestPlugin('b'),
c: new TestPlugin('c')
};
// Act
const resolver = new CustomResolver(lossless, plugins);
// Access private method for testing
const graph = resolver.dependencyGraph;
// Assert
expect(graph.get('a')).toBeDefined();
expect(graph.get('b')).toBeDefined();
expect(graph.get('c')).toBeDefined();
// No dependencies should be set
expect(Array.from(graph.get('a') || [])).toHaveLength(0);
expect(Array.from(graph.get('b') || [])).toHaveLength(0);
expect(Array.from(graph.get('c') || [])).toHaveLength(0);
});
test('should detect circular dependencies', () => {
// Arrange
const plugins = {
a: new TestPlugin('a', ['c']), // a depends on c
b: new TestPlugin('b', ['a']), // b depends on a
c: new TestPlugin('c', ['b']) // c depends on b (circular)
};
// Act & Assert
expect(() => {
new CustomResolver(lossless, plugins);
}).toThrow('Circular dependency detected in plugin dependencies');
});
});
});

10
__tests__/unit/views/resolvers/last-write-wins.test.ts
View File

@ -1,8 +1,8 @@
import Debug from "debug";
import { createDelta } from '@src/core/delta-builder';
import { Lossless, RhizomeNode } from '@src';
import { TimestampResolver } from '@src/views/resolvers/timestamp-resolvers';
const debug = Debug('rz:test:last-write-wins');
import { createDelta } from '../../../../src/core/delta-builder';
import { Lossless, RhizomeNode } from '../../../../src';
import { TimestampResolver } from '../../../../src/views/resolvers/timestamp-resolvers';
const debug = Debug('test:last-write-wins');
// This was initially written to test a LastWriteWins resolver, but that has been
// superceded by the TimestampResolver.
@ -27,7 +27,7 @@ describe('Last write wins', () => {
);
});
test('our resolver should return the most recently written value', () => {
it('our resolver should return the most recently written value', () => {
const result = lossy.resolve(["broccoli"]);
debug('result', result);
expect(result).toMatchObject({

222
__tests__/unit/views/resolvers/state-visibility.test.ts
View File

@ -1,222 +0,0 @@
import { RhizomeNode, Lossless, createDelta } from "@src";
import { CollapsedDelta } from "@src/views/lossless";
import {
CustomResolver,
ResolverPlugin,
LastWriteWinsPlugin,
DependencyStates
} from "@src/views/resolvers/custom-resolvers";
import { PropertyTypes } from '@src/core/types';
describe('State Visibility', () => {
let node: RhizomeNode;
let lossless: Lossless;
beforeEach(() => {
node = new RhizomeNode();
lossless = new Lossless(node);
});
// A test plugin that records which states it sees
class StateSpyPlugin implements ResolverPlugin<{ values: string[] }, 'dependsOn'> {
readonly dependencies = [] as const;
seenStates: Record<string, unknown>[] = [];
initialize() {
return { values: [] };
}
update(
currentState: { values: string[] },
newValue: PropertyTypes,
_delta: CollapsedDelta,
dependencies: DependencyStates
) {
// Record the states we can see
this.seenStates.push({ ...dependencies });
// Just store the string representation of the value
return {
values: [...currentState.values, String(newValue)]
};
}
resolve(
state: { values: string[] },
_dependencies: DependencyStates
): string {
// Always return a value, even if empty
return state.values.join(',') || 'default';
}
}
// A simple plugin that depends on another property
class DependentPlugin implements ResolverPlugin<{ value: string }, 'dependsOn'> {
readonly dependencies = ['dependsOn'] as const;
seenStates: Record<string, unknown>[] = [];
initialize() {
return { value: '' };
}
update(
_currentState: { value: string },
newValue: PropertyTypes,
_delta: CollapsedDelta,
dependencies: DependencyStates
) {
this.seenStates.push({ ...dependencies });
return { value: String(newValue) };
}
resolve(
state: { value: string },
_dependencies: DependencyStates
): string {
return state.value;
}
}
test('plugins should only see their declared dependencies', async () => {
// Create a resolver with two independent plugins
const spy1 = new StateSpyPlugin();
const spy2 = new StateSpyPlugin();
const config = {
prop1: spy1,
prop2: spy2
} as const;
const resolver = new CustomResolver(lossless, config);
// Add some data
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'prop1', 'value1', 'prop1')
.setProperty('entity1', 'prop2', 'value2', 'prop2')
.buildV1()
);
// Trigger resolution
const results = resolver.resolve();
// The result should contain the entity with both properties
const entity = results?.['entity1'];
expect(entity).toBeDefined();
if (!entity) return;
expect(entity.properties).toHaveProperty('prop1');
expect(entity.properties).toHaveProperty('prop2');
// Since we're not testing the order of processing here,
// we'll just verify that at least one of the spies was called
expect(
spy1.seenStates.length > 0 ||
spy2.seenStates.length > 0
).toBe(true);
});
test('plugins should see their declared dependencies', async () => {
const dependent = new DependentPlugin();
const dependency = new StateSpyPlugin();
const config = {
dependent,
dependsOn: dependency
} as const;
const resolver = new CustomResolver(lossless, config);
// Add some data
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'dependsOn', 'baseValue', 'prop1')
.setProperty('entity1', 'dependent', 'dependentValue', 'prop2')
.buildV1()
);
// Trigger resolution
const result = resolver.resolve();
expect(result).toBeDefined();
// The dependent plugin's update method won't be called by resolve()
// So we can't test the seenStates here. Instead, we'll test the result
expect(result).toBeDefined();
if (!result) return;
const entity = result['entity1'];
expect(entity).toBeDefined();
expect(entity.properties).toHaveProperty('dependent');
});
test('plugins should not see undeclared dependencies', async () => {
const dependent = new DependentPlugin();
const lastWrite = new LastWriteWinsPlugin();
const other = new LastWriteWinsPlugin();
const resolver = new CustomResolver(lossless, {
dependent: dependent,
dependsOn: lastWrite,
other: other // Not declared as a dependency
});
// Add some data
lossless.ingestDelta(
createDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'dependsOn', 'baseValue', 'prop1')
.setProperty('entity1', 'other', 'otherValue', 'prop2')
.setProperty('entity1', 'dependent', 'dependentValue', 'prop3')
.buildV1()
);
// Trigger resolution
const results = resolver.resolve();
expect(results).toBeDefined();
if (!results) return;
// The result should contain the entity with both properties
const entity = results['entity1'];
expect(entity).toBeDefined();
if (!entity) return;
expect(entity.properties).toHaveProperty('dependent');
expect(entity.properties).toHaveProperty('dependsOn');
expect(entity.properties).toHaveProperty('other');
});
test('should throw error for unknown dependencies', () => {
class PluginWithBadDeps implements ResolverPlugin<{ value: string }, 'nonexistent'> {
readonly dependencies = ['nonexistent'] as const;
initialize() {
return { value: '' };
}
update(
currentState: { value: string },
_newValue: PropertyTypes,
_delta: CollapsedDelta,
_dependencies: DependencyStates
) {
return currentState;
}
resolve(
state: { value: string },
_dependencies: DependencyStates
): string {
return state.value;
}
}
expect(() => {
new CustomResolver(lossless, {
bad: new PluginWithBadDeps()
});
}).toThrow("Plugin 'bad' depends on unknown property: nonexistent");
});
});

314
docs/custom-resolvers.md Normal file
View File

@ -0,0 +1,314 @@
# Custom Resolvers
## Overview
The `CustomResolver` class provides a flexible system for resolving property conflicts in a distributed system. This document covers the implementation details, including the support for inter-plugin dependencies.
## Current Implementation
### Core Components
1. **ResolverPlugin Interface**
- Defines the contract for all resolver implementations
- Key methods:
- `initialize()`: Creates initial state
- `update()`: Processes new values with timestamps
- `resolve()`: Produces final value from accumulated state
2. **CustomResolver Class**
- Manages resolution of entity properties using configured plugins
- Implements the core resolution logic:
- `initializer`: Creates initial state structure
- `reducer`: Processes deltas and updates state using plugins
- `resolver`: Produces final resolved values
3. **Built-in Plugins**
- `LastWriteWinsPlugin`: Keeps the most recent value
- `FirstWriteWinsPlugin`: Keeps the first value seen
- `ConcatenationPlugin`: Combines string values with a separator
- `MajorityVotePlugin`: Selects the most common value
- `MinPlugin`/`MaxPlugin`: Tracks minimum/maximum numeric values
## Plugin Dependencies
### Overview
The system supports explicit declaration of dependencies between plugins, ensuring they are processed in the correct order. This enables:
1. **Deterministic Execution**: Plugins are processed after their dependencies
2. **Dependency Validation**: Circular dependencies are detected and prevented
3. **Optimized Processing**: Only necessary states are processed in the correct order
### Declaring Dependencies
Each plugin can declare its dependencies using the `dependencies` property:
```typescript
class MyPlugin implements ResolverPlugin {
name = 'my-plugin';
// List of property IDs this plugin depends on
dependencies: PropertyID[] = ['other-property'];
// ... rest of the implementation
}
```
### Dependency Resolution
1. **Topological Sorting**: Plugins are processed in an order that respects their dependencies
2. **Cycle Detection**: Circular dependencies are detected during initialization
3. **Lazy Resolution**: Dependencies are only resolved when needed
### Example: Chained Dependencies
```typescript
const resolver = new CustomResolver(losslessView, {
// This will be processed first (no dependencies)
basePrice: new LastWriteWinsPlugin(),
// This depends on basePrice
tax: new TaxCalculatorPlugin(),
// This depends on both basePrice and tax
total: new TotalCalculatorPlugin()
});
```
### Best Practices
1. **Minimal Dependencies**: Only declare dependencies that are actually needed
2. **Avoid Cycles**: Design your plugins to avoid circular dependencies
3. **Document Dependencies**: Clearly document what each plugin depends on
4. **Test Dependencies**: Include tests that verify the dependency behavior
### Implementation Details
#### ResolverPlugin Interface
The `ResolverPlugin` interface defines the contract that all resolver plugins must implement. It has been updated to support inter-plugin dependencies and state sharing:
```typescript
interface ResolverPlugin<T = unknown> {
// Unique name of the plugin
name: string;
// List of property IDs this plugin depends on
// Plugins will be processed after their dependencies
dependencies?: PropertyID[];
// Initialize the state for a property
initialize(): T;
// Process a new value for the property
update(
currentState: T,
newValue: PropertyTypes,
delta: CollapsedDelta,
allStates?: Record<PropertyID, unknown>
): T;
// Resolve the final value from the current state
// Must return a value of type PropertyTypes or undefined
// This is the value that will be used as the resolved property value
resolve(
state: T,
allStates?: Record<PropertyID, unknown>
): PropertyTypes | undefined;
}
```
#### Important Notes
1. **Return Type of `resolve`**:
- The `resolve` method must return a value of type `PropertyTypes` or `undefined`
- This is different from the `update` method which returns the updated state of type `T`
- The returned value will be used as the resolved property value
2. **Plugin Dependencies**:
- Dependencies are declared using the `dependencies` property
- Dependencies should be an array of property IDs that this plugin depends on
- The resolver ensures that all dependencies are processed before the plugin that depends on them
3. **State Access**:
- The `allStates` parameter in `update` and `resolve` provides access to the current state of all other properties
- This allows plugins to make decisions based on the state of other properties
- The states are keyed by property ID and contain the raw state objects for each plugin
4. **Error Handling**:
- If a plugin throws an error during initialization, update, or resolve, the error will be logged and the plugin will be skipped
- It's recommended to handle errors within the plugin methods when possible
#### CustomResolver Class
The `CustomResolver` class has been enhanced to:
1. Collect all plugin states before processing updates
2. Pass the complete state to each plugin during updates and resolution
### Complex Example: Discounted Price with Dependencies
This example demonstrates a more complex scenario with multiple interdependent plugins:
Here's a practical example of a plugin that calculates a discounted price based on another property:
```typescript
class DiscountedPricePlugin implements ResolverPlugin<{ price: number }> {
name = 'discounted-price';
initialize() {
return { price: 0 };
}
update(
state: { price: number },
newValue: PropertyTypes,
_delta: CollapsedDelta,
_allStates?: Record<PropertyID, unknown>
) {
if (typeof newValue === 'number') {
return { price: newValue };
}
return state;
}
resolve(
state: { price: number },
allStates?: Record<PropertyID, unknown>
): number | undefined {
// Access the discount value from another plugin's state
const discountState = allStates?.['discount'] as { value: number } | undefined;
if (discountState) {
// Apply discount if available
return state.price * (1 - (discountState.value / 100));
}
return state.price;
}
}
// Usage with a discount plugin
const resolver = new CustomResolver(losslessView, {
price: new DiscountedPricePlugin(),
discount: new LastWriteWinsPlugin()
});
```
### Best Practices
1. **Dependency Management**:
- Clearly document which properties your plugin depends on
- Handle cases where dependencies might be undefined
- Consider using TypeScript type guards for safer property access
2. **Performance Considerations**:
- Access only the states you need in the `allStates` object
- Consider caching resolved values if the same calculation is performed multiple times
3. **Testing**:
- Test plugins with and without their dependencies
- Verify behavior when dependencies are updated in different orders
- Test edge cases like missing or invalid dependencies
### Built-in Plugins
All built-in plugins have been updated to be compatible with the new interface:
- `LastWriteWinsPlugin`
- `FirstWriteWinsPlugin`
- `ConcatenationPlugin`
- `MajorityVotePlugin`
- `MinPlugin`
- `MaxPlugin`
These plugins maintain backward compatibility while supporting the new functionality.
## Implementation Status
The inter-plugin dependency feature has been implemented and includes:
1. Updated `ResolverPlugin` interface with `allStates` parameter
2. Enhanced `CustomResolver` class for state sharing between plugins
3. Updated all built-in plugins for compatibility
4. Comprehensive test coverage including:
- Basic functionality of all built-in plugins
- Inter-plugin dependency scenarios
- Edge cases and error conditions
5. Complete documentation with examples
## Usage Examples
### Basic Usage
```typescript
const resolver = new CustomResolver(losslessView, {
title: new LastWriteWinsPlugin(),
price: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin()
});
```
### With Dependent Plugins
```typescript
const resolver = new CustomResolver(losslessView, {
basePrice: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin(),
finalPrice: new DiscountedPricePlugin() // Depends on discount
});
```
### Complex Example
```typescript
const resolver = new CustomResolver(losslessView, {
// Basic properties
name: new LastWriteWinsPlugin(),
description: new ConcatenationPlugin(' '),
// Pricing
basePrice: new LastWriteWinsPlugin(),
taxRate: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin(),
// Calculated fields
subtotal: new SubtotalCalculator(), // Uses basePrice and quantity
tax: new TaxCalculator(), // Uses subtotal and taxRate
total: new TotalCalculator() // Uses subtotal, tax, and discount
});
```
## Future Enhancements
1. **Plugin Dependencies**: Explicitly declare dependencies between plugins
2. **Caching**: Cache resolved values for better performance
3. **Validation**: Add validation to prevent circular dependencies
4. **Debugging**: Add logging for plugin execution order and state access
5. **Optimization**: Lazy-load plugin states to improve performance with many properties
## Example Configurations
### Basic Usage
```typescript
const resolver = new CustomResolver(losslessView, {
title: new LastWriteWinsPlugin(),
price: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin()
});
```
### With Dependent Plugins
```typescript
const resolver = new CustomResolver(losslessView, {
basePrice: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin(),
finalPrice: new DiscountedPricePlugin()
});
```
## Future Enhancements
1. **Plugin Dependencies**: Explicitly declare dependencies between plugins
2. **Caching**: Cache resolved values for better performance
3. **Validation**: Add validation to prevent circular dependencies
4. **Debugging**: Add logging for plugin execution order and state access

204
docs/custom-resolvers/api/custom-resolver-class.md
View File

@ -1,204 +0,0 @@
# CustomResolver Class
## Overview
The `CustomResolver` class is the main entry point for the Custom Resolver system. It manages the resolution of entity properties using the configured plugins and handles dependency resolution between them.
## Class Definition
```typescript
class CustomResolver {
/**
* Creates a new CustomResolver instance
* @param view The lossless view to resolve
* @param config Plugin configuration
*/
constructor(
private readonly view: LosslessView,
private readonly config: ResolverConfig
);
/**
* Processes all entities in the view and returns the resolved values
*/
resolve(): CustomResolverResult;
/**
* Processes a single entity and returns its resolved values
* @param entityId ID of the entity to resolve
*/
resolveEntity(entityId: string): EntityResult | undefined;
/**
* Gets the current processing order of properties
*/
getProcessingOrder(): string[];
/**
* Gets the dependency graph
*/
getDependencyGraph(): Map<string, Set<string>>;
}
```
## Constructor
### `new CustomResolver(view, config)`
Creates a new instance of the CustomResolver.
**Parameters:**
- `view: LosslessView` - The lossless view containing the data to resolve
- `config: ResolverConfig` - Configuration object mapping property IDs to their resolver plugins
**Example:**
```typescript
const resolver = new CustomResolver(view, {
price: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin(),
total: new TotalPricePlugin()
});
```
## Methods
### `resolve(): CustomResolverResult`
Processes all entities in the view and returns the resolved values.
**Returns:** `CustomResolverResult` - Object mapping entity IDs to their resolved properties
**Example:**
```typescript
const results = resolver.resolve();
debug(results);
// {
// 'entity1': {
// id: 'entity1',
// properties: { price: 100, discount: 10, total: 90 }
// },
// // ...
// }
```
### `resolveEntity(entityId: string): EntityResult | undefined`
Processes a single entity and returns its resolved values.
**Parameters:**
- `entityId: string` - ID of the entity to resolve
**Returns:** `EntityResult | undefined` - Resolved entity or undefined if not found
**Example:**
```typescript
const result = resolver.resolveEntity('order-123');
if (result) {
debug(`Order total: ${result.properties.total}`);
}
```
### `getProcessingOrder(): string[]`
Gets the current processing order of properties based on their dependencies.
**Returns:** `string[]` - Array of property IDs in processing order
**Example:**
```typescript
const order = resolver.getProcessingOrder();
debug('Processing order:', order);
// ['price', 'discount', 'total']
```
### `getDependencyGraph(): Map<string, Set<string>>`
Gets the dependency graph used for resolution.
**Returns:** `Map<string, Set<string>>` - Map where keys are property IDs and values are sets of their dependencies
**Example:**
```typescript
const graph = resolver.getDependencyGraph();
for (const [prop, deps] of graph.entries()) {
debug(`${prop} depends on:`, [...deps]);
}
```
## Configuration
The resolver is configured with an object mapping property IDs to their resolver plugins:
```typescript
interface ResolverConfig {
[propertyId: string]: ResolverPlugin<any, string>;
}
```
## Error Handling
The resolver may throw the following errors:
- `Error` - For invalid configurations or dependency cycles
- `TypeError` - For type mismatches or invalid plugin implementations
## Example: Complete Usage
```typescript
import { CustomResolver, LastWriteWinsPlugin } from './resolver';
import { LosslessView } from '../lossless-view';
// Create a lossless view with some data
const view = new LosslessView();
// ... add data to the view ...
// Configure the resolver
const resolver = new CustomResolver(view, {
// Simple plugins
productId: new LastWriteWinsPlugin(),
quantity: new LastWriteWinsPlugin(),
// Plugin with dependencies
unitPrice: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin(),
taxRate: new LastWriteWinsPlugin(),
// Complex plugin with multiple dependencies
subtotal: new class implements ResolverPlugin<SubtotalState, 'unitPrice' | 'quantity'> {
readonly dependencies = ['unitPrice', 'quantity'] as const;
initialize() { return { value: 0 }; }
update(_state, _value, _delta, deps) {
const unitPrice = deps.unitPrice as number;
const quantity = deps.quantity as number;
return { value: unitPrice * quantity };
}
resolve(state) { return state.value; }
}(),
// More plugins...
});
// Resolve all entities
const results = resolver.resolve();
debug(results);
// Or resolve a single entity
const order = resolver.resolveEntity('order-123');
debug(order);
```
## Best Practices
1. **Reuse Instances**: Create a single resolver instance and reuse it
2. **Minimize Dependencies**: Keep the dependency graph simple and acyclic
3. **Error Handling**: Always handle potential errors in plugin implementations
4. **Performance**: Be mindful of plugin complexity in hot code paths
## Related
- [ResolverPlugin Interface](./resolver-plugin-interface.md)
- [Creating Custom Plugins](../plugins/creating-plugins.md)
- [Dependency Resolution](../dependencies/dependency-resolution.md)

173
docs/custom-resolvers/api/resolver-plugin-interface.md
View File

@ -1,173 +0,0 @@
# ResolverPlugin Interface
## Overview
The `ResolverPlugin` interface defines the contract that all resolver plugins must implement. It provides type-safe access to plugin state and dependencies.
## Interface Definition
```typescript
interface ResolverPlugin<T = unknown, D extends string = never> {
/**
* Unique identifier for the plugin
*/
readonly name: string;
/**
* Array of property IDs this plugin depends on
* @default []
*/
readonly dependencies?: readonly D[];
/**
* Initializes the plugin's state
* @returns Initial state object
*/
initialize(): T;
/**
* Processes a new value and updates the plugin's state
* @param currentState Current plugin state
* @param newValue New value to process
* @param delta Delta information
* @param dependencies Resolved states of all declared dependencies
* @returns Updated plugin state
*/
update(
currentState: T,
newValue: PropertyTypes,
delta: CollapsedDelta,
dependencies: DependencyStates
): T;
/**
* Resolves the final value from the current state
* @param state Current plugin state
* @param dependencies Resolved states of all declared dependencies
* @returns Resolved value or undefined if no value should be set
*/
resolve(
state: T,
dependencies: DependencyStates
): PropertyTypes | undefined;
}
```
## Type Parameters
| Parameter | Description |
|-----------|-------------|
| `T` | Type of the plugin's internal state |
| `D` | Union type of dependency names (must extend `string`) |
## Methods
### `initialize()`
Initializes the plugin's internal state. Called once when the resolver is created.
**Returns:** `T` - The initial state object
### `update(currentState, newValue, delta, dependencies)`
Processes a new value and updates the plugin's state.
**Parameters:**
- `currentState: T` - Current plugin state
- `newValue: PropertyTypes` - New value to process
- `delta: CollapsedDelta` - Delta information
- `dependencies: DependencyStates` - Resolved states of all declared dependencies
**Returns:** `T` - Updated plugin state
### `resolve(state, dependencies)`
Resolves the final value from the current state.
**Parameters:**
- `state: T` - Current plugin state
- `dependencies: DependencyStates` - Resolved states of all declared dependencies
**Returns:** `PropertyTypes | undefined` - Resolved value or undefined if no value should be set
## Example Implementation
```typescript
class CounterPlugin implements ResolverPlugin<CounterState> {
initialize(): CounterState {
return { count: 0 };
}
update(
state: CounterState,
_newValue: unknown,
_delta: CollapsedDelta,
_deps: {}
): CounterState {
return { count: state.count + 1 };
}
resolve(state: CounterState): number {
return state.count;
}
}
```
## Best Practices
1. **Immutability**: Always return new state objects instead of mutating
2. **Purity**: Keep methods pure and side-effect free
3. **Error Handling**: Handle unexpected input gracefully
4. **Documentation**: Document expected types and behavior
## Common Patterns
### Accessing Dependencies
```typescript
class PriceCalculator implements ResolverPlugin<PriceState, 'basePrice' | 'taxRate'> {
readonly dependencies = ['basePrice', 'taxRate'] as const;
update(
_state: PriceState,
_newValue: unknown,
_delta: CollapsedDelta,
deps: DependencyStates,
): PriceState {
const basePrice = deps.basePrice as number;
const taxRate = deps.taxRate as number;
return { total: basePrice * (1 + taxRate) };
}
// ...
}
```
### Optional Dependencies
```typescript
class OptionalDepPlugin implements ResolverPlugin<State, 'required' | 'optional?'> {
readonly dependencies = ['required', 'optional?'] as const;
update(
state: State,
_newValue: unknown,
_delta: CollapsedDelta,
deps: any,
): State {
const required = deps.required as number; // Always present
const optional = deps['optional?'] as number | undefined; // Might be undefined
// ...
}
// ...
}
```
## Related
- [Creating Custom Plugins](../plugins/creating-plugins.md)
- [Type-Safe Dependencies](../dependencies/type-safety.md)
- [CustomResolver Class](./custom-resolver-class.md)

273
docs/custom-resolvers/api/types.md
View File

@ -1,273 +0,0 @@
# Common Types and Interfaces
This document describes the common types and interfaces used throughout the Custom Resolver system.
## Core Types
### `PropertyID`
```typescript
type PropertyID = string;
```
Unique identifier for a property.
### `PropertyTypes`
```typescript
type PropertyTypes =
| string
| number
| boolean
| null
| undefined
| PropertyTypes[]
| { [key: string]: PropertyTypes };
```
All possible property value types that can be handled by the resolver.
### `DependencyStates`
```typescript
type DependencyStates = {
[K in D]: unknown;
};
```
Maps dependency names to their resolved values. The actual type of each value depends on the plugin that produced it.
### `CollapsedDelta`
```typescript
interface CollapsedDelta {
timestamp: number;
source?: string;
// ... other delta metadata
}
```
Represents a collapsed delta with metadata about the change.
## Plugin Types
### `ResolverPlugin<T, D>`
```typescript
interface ResolverPlugin<T = unknown, D extends string = never> {
readonly name: string;
readonly dependencies?: readonly D[];
initialize(): T;
update(
currentState: T,
newValue: PropertyTypes,
delta: CollapsedDelta,
dependencies: DependencyStates
): T;
resolve(
state: T,
dependencies: DependencyStates
): PropertyTypes | undefined;
}
```
The main plugin interface. See [ResolverPlugin Interface](./resolver-plugin-interface.md) for details.
## Result Types
### `EntityResult`
```typescript
interface EntityResult {
id: string;
properties: {
[propertyId: string]: PropertyTypes;
};
}
```
A basic map of some results. May represent entites, entity properties, or arbitrary synthetic attributes.
### `CustomResolverResult`
```typescript
interface CustomResolverResult {
[entityId: string]: EntityResult;
}
```
Maps entity IDs to their resolved properties.
## Configuration Types
### `ResolverConfig`
```typescript
interface ResolverConfig {
[propertyId: string]: ResolverPlugin<any, string>;
}
```
Configuration object mapping property IDs to their resolver plugins.
## Built-in Plugin Types
### `LastWriteWinsPlugin`
```typescript
class LastWriteWinsPlugin implements ResolverPlugin<LastWriteWinsState> {
// ...
}
interface LastWriteWinsState {
value?: PropertyTypes;
timestamp: number;
}
```
### `FirstWriteWinsPlugin`
```typescript
class FirstWriteWinsPlugin implements ResolverPlugin<FirstWriteWinsState> {
// ...
}
interface FirstWriteWinsState {
value?: PropertyTypes;
isSet: boolean;
}
```
### `ConcatenationPlugin`
```typescript
interface ConcatenationOptions {
separator?: string;
sort?: boolean;
}
class ConcatenationPlugin implements ResolverPlugin<ConcatenationState> {
constructor(private options: ConcatenationOptions = {}) {
this.options = {
separator: options.separator || ', ',
sort: options.sort || false
};
}
// ...
}
interface ConcatenationState {
values: Set<string>;
separator: string;
sort: boolean;
}
```
### `MajorityVotePlugin`
```typescript
interface MajorityVoteOptions {
minVotes?: number;
}
class MajorityVotePlugin implements ResolverPlugin<MajorityVoteState> {
constructor(private options: MajorityVoteOptions = {}) {
this.options = {
minVotes: options.minVotes || 1
};
}
// ...
}
interface MajorityVoteState {
votes: Map<string, number>;
minVotes: number;
}
```
## Type Utilities
### `DependencyKeys<T>`
Extracts the dependency keys from a plugin type.
```typescript
type DependencyKeys<T> =
T extends ResolverPlugin<any, infer D> ? D : never;
```
### `PluginState<T>`
Extracts the state type from a plugin type.
```typescript
type PluginState<T> =
T extends ResolverPlugin<infer S, any> ? S : never;
```
## Example: Working with Types
### Type-Safe Plugin Implementation
```typescript
// Define state and dependency types
interface CounterState {
count: number;
}
type CounterDeps = 'incrementBy' | 'resetThreshold';
// Implement plugin with type safety
class CounterPlugin implements ResolverPlugin<CounterState, CounterDeps> {
readonly dependencies = ['incrementBy', 'resetThreshold'] as const;
initialize(): CounterState {
return { count: 0 };
}
update(
state: CounterState,
_newValue: unknown,
_delta: CollapsedDelta,
deps: DependencyStates
): CounterState {
const increment = deps.incrementBy as number;
const threshold = deps.resetThreshold as number;
const newCount = state.count + increment;
return {
count: newCount >= threshold ? 0 : newCount
};
}
resolve(state: CounterState): number {
return state.count;
}
}
```
## Type Assertions
When working with dependency values, you'll often need to use type assertions since they're typed as `unknown`:
```typescript
// Type assertion
const value = deps.someDependency as SomeType;
// Type guard
if (typeof deps.someDependency === 'number') {
// deps.someDependency is now typed as number
}
```
## Best Practices
1. **Use `as const`** for string literals to get the most specific type
2. **Narrow types** when accessing dependency values
3. **Document expected types** in JSDoc comments
4. **Handle undefined** values when dependencies might be missing
5. **Use type guards** for runtime type safety when needed

102
docs/custom-resolvers/dependencies/dependency-resolution.md
View File

@ -1,102 +0,0 @@
# Dependency Resolution
## Overview
The Custom Resolver system includes a robust dependency resolution mechanism that ensures plugins are processed in the correct order based on their dependencies. This document explains how the resolution process works and how to work with complex dependency graphs.
## How Dependency Resolution Works
1. **Graph Construction**: The system builds a directed graph of plugin dependencies during initialization.
2. **Cycle Detection**: The graph is checked for cycles to prevent infinite loops.
3. **Topological Sort**: Plugins are ordered such that all dependencies are processed before the plugins that depend on them.
4. **State Resolution**: During processing, each plugin receives the resolved states of its dependencies.
## Example: Resolving Dependencies
Consider the following plugin configuration:
```typescript
const resolver = new CustomResolver(view, {
basePrice: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin(),
taxRate: new LastWriteWinsPlugin(),
tax: new TaxCalculatorPlugin(), // Depends on basePrice and taxRate
total: new TotalPricePlugin() // Depends on basePrice, discount, and tax
});
```
The system will automatically determine the correct processing order:
1. `basePrice`, `discount`, `taxRate` (no dependencies)
2. `tax` (depends on basePrice and taxRate)
3. `total` (depends on basePrice, discount, and tax)
## Handling Circular Dependencies
Circular dependencies are detected during initialization and will result in an error. For example:
```typescript
// This will throw an error during initialization
const resolver = new CustomResolver(view, {
a: new SomePlugin({ deps: ['b'] }),
b: new SomePlugin({ deps: ['a'] }) // Circular dependency!
});
```
## Advanced Dependency Patterns
### Optional Dependencies
To make a dependency optional, mark it with a `?` suffix:
```typescript
class MyPlugin implements ResolverPlugin<MyState, 'required' | 'optional?'> {
readonly dependencies = ['required', 'optional?'] as const;
// ...
}
```
### Dynamic Dependencies
For plugins that need to determine dependencies at runtime, you can implement a custom resolver:
```typescript
class DynamicDepsPlugin implements ResolverPlugin<DynamicState> {
getDependencies(config: any): string[] {
// Determine dependencies based on config
return ['always'];
}
// ...
}
```
## Debugging Dependency Issues
### Common Issues
1. **Missing Dependencies**: Ensure all required dependencies are declared
2. **Type Mismatches**: Verify that dependency types match expected types
3. **Circular Dependencies**: Break circular references in your dependency graph
### Debugging Tools
1. **Dependency Graph**: Use `resolver.getDependencyGraph()` to inspect the dependency graph
2. **Processing Order**: Check `resolver.getProcessingOrder()` to see the resolved execution order
3. **Logging**: Enable debug logging to track dependency resolution
## Performance Considerations
1. **Dependency Depth**: Deep dependency chains can impact performance
2. **Graph Complexity**: Complex graphs take longer to process
3. **Caching**: The system caches resolved dependencies for performance
## Best Practices
1. **Minimize Dependencies**: Only depend on what you need
2. **Keep Graphs Shallow**: Prefer wide, shallow dependency graphs over deep ones
3. **Document Dependencies**: Clearly document all plugin dependencies
4. **Test Edge Cases**: Test with missing or invalid dependencies
5. **Monitor Performance**: Keep an eye on resolution time for large graphs

58
docs/custom-resolvers/dependencies/index.md
View File

@ -1,58 +0,0 @@
# Plugin Dependencies
## Overview
The Custom Resolver system provides a powerful dependency management system that allows plugins to depend on the resolved values of other properties. This enables complex resolution strategies where the value of one property can influence how another property is resolved.
## Key Concepts
1. **Dependency Declaration**: Plugins declare their dependencies using the `dependencies` property
2. **Type Safety**: Dependencies are type-checked at compile time
3. **Automatic Resolution**: The system resolves dependencies in the correct order
4. **Cycle Detection**: Circular dependencies are detected and reported
## How It Works
1. **Dependency Graph**: The system builds a directed acyclic graph (DAG) of plugin dependencies
2. **Topological Sort**: Plugins are processed in an order that respects their dependencies
3. **Dependency Injection**: Required dependencies are automatically injected into plugin methods
4. **Lazy Resolution**: Dependencies are only resolved when needed
## Example
```typescript
class TotalPricePlugin implements ResolverPlugin<TotalState, 'price' | 'tax'> {
readonly dependencies = ['price', 'tax'] as const;
initialize(): TotalState {
return { total: 0 };
}
update(
state: TotalState,
_newValue: unknown,
_delta: CollapsedDelta,
deps: DependencyStates
): TotalState {
const price = deps.price as number;
const tax = deps.tax as number;
return { total: price + tax };
}
resolve(state: TotalState): number {
return state.total;
}
}
```
## Best Practices
1. **Minimal Dependencies**: Only declare dependencies that are actually needed
2. **Acyclic Dependencies**: Keep the dependency graph acyclic
3. **Document Dependencies**: Clearly document what each dependency is used for
4. **Handle Missing Dependencies**: Gracefully handle cases where dependencies might be undefined
## Next Steps
- Learn about [Type-Safe Dependencies](./type-safety.md)
- Understand [Dependency Resolution](./dependency-resolution.md)

146
docs/custom-resolvers/dependencies/type-safety.md
View File

@ -1,146 +0,0 @@
# Type-Safe Dependencies
## Overview
The Custom Resolver system leverages TypeScript's type system to provide compile-time safety for plugin dependencies. This ensures that:
1. Only declared dependencies can be accessed
2. Dependencies are properly typed
3. Refactoring is safer with compiler support
4. Common errors are caught during development
## How It Works
The `ResolverPlugin` interface uses TypeScript generics to enforce type safety:
```typescript
interface ResolverPlugin<T = unknown, D extends string = never> {
readonly name: string;
readonly dependencies?: readonly D[];
// ... methods receive properly typed dependencies
update(
currentState: T,
newValue: PropertyTypes,
delta: CollapsedDelta,
dependencies: DependencyStates
): T;
}
type DependencyStates = {
[K in D]: unknown;
};
```
## Declaring Dependencies
Dependencies are declared as a readonly array of string literals:
```typescript
class MyPlugin implements ResolverPlugin<MyState, 'dep1' | 'dep2'> {
readonly dependencies = ['dep1', 'dep2'] as const;
// ... implementation
}
```
### Type Inference
Using `as const` with the dependencies array ensures TypeScript infers the most specific type possible:
```typescript
// Type is readonly ["dep1", "dep2"]
readonly dependencies = ['dep1', 'dep2'] as const;
```
## Accessing Dependencies
Dependencies are accessed through the `dependencies` parameter in plugin methods:
```typescript
update(
state: MyState,
_newValue: unknown,
_delta: CollapsedDelta,
deps: DependencyStates
): MyState {
// TypeScript knows price and tax are available
const price = deps.price as number;
const tax = deps.tax as number;
// This would be a TypeScript error:
// const unknown = deps.unknown; // Error: Property 'unknown' does not exist
return { /* ... */ };
}
```
## Type Assertions
Since dependency values are typed as `unknown`, you'll need to use type assertions or type guards:
```typescript
// Using type assertion
const price = deps.price as number;
// Using type guard
if (typeof deps.price === 'number') {
// deps.price is now typed as number
}
```
## Best Practices
1. **Use `as const`** for dependency arrays to get the most specific type
2. **Narrow types** when accessing dependency values
3. **Document expected types** of dependencies in JSDoc
4. **Handle undefined** values when dependencies might be missing
## Common Patterns
### Optional Dependencies
```typescript
class MyPlugin implements ResolverPlugin<MyState, 'required' | 'optional?'> {
readonly dependencies = ['required', 'optional?'] as const;
update(_state: MyState, _value: unknown, _delta: CollapsedDelta, deps: any) {
const required = deps.required as number; // Always present
const optional = deps['optional?'] as number | undefined; // Might be undefined
// ...
}
}
```
### Multiple Dependencies with Same Type
```typescript
type PriceDependencies = 'price1' | 'price2' | 'price3';
class PriceAggregator implements ResolverPlugin<PriceState, PriceDependencies> {
readonly dependencies: readonly PriceDependencies[] = ['price1', 'price2', 'price3'] as const;
update(_state: PriceState, _value: unknown, _delta: CollapsedDelta, deps: any) {
const prices = this.dependencies
.map(dep => deps[dep] as number | undefined)
.filter((p): p is number => p !== undefined);
// ...
}
}
```
## Troubleshooting
### Type Errors
- **Missing Dependencies**: Ensure all dependencies are properly declared in the type parameter
- **Incorrect Types**: Verify type assertions match the expected types
- **Readonly Arrays**: Use `readonly` and `as const` for dependency arrays
### Runtime Errors
- **Undefined Dependencies**: Check if a dependency exists before using it
- **Type Mismatches**: Validate types at runtime when necessary
- **Circular Dependencies**: Ensure your dependency graph is acyclic

47
docs/custom-resolvers/overview.md
View File

@ -1,47 +0,0 @@
# Custom Resolvers
## Overview
The `CustomResolver` system provides a flexible framework for resolving property conflicts in distributed systems. It enables you to define custom resolution strategies through plugins, complete with type-safe dependencies between resolvers.
## Key Features
- **Plugin-based Architecture**: Extend functionality with custom resolvers
- **Type-Safe Dependencies**: Compile-time checking of plugin dependencies
- **Built-in Resolvers**: Common resolution strategies included
- **Efficient Processing**: Only processes changed deltas
- **Deterministic Results**: Same input always produces the same output
## Core Concepts
1. **Resolver Plugins**: Implement resolution logic for properties
2. **Dependency Management**: Declare and manage dependencies between plugins
3. **State Management**: Maintain and update state based on incoming deltas
4. **Resolution Pipeline**: Process updates and resolve final values
## Getting Started
```typescript
import { CustomResolver, LastWriteWinsPlugin } from './resolver';
import { LosslessView } from '../lossless-view';
// Create a lossless view
const view = new LosslessView();
// Create a resolver with a last-write-wins strategy
const resolver = new CustomResolver(view, {
myProperty: new LastWriteWinsPlugin()
});
// Process updates
// ...
// Get resolved values
const result = resolver.resolve();
```
## Next Steps
- Learn about [Built-in Plugins](./plugins/builtin-plugins.md)
- Understand [Type-Safe Dependencies](./dependencies/type-safety.md)
- Explore [Creating Custom Plugins](./plugins/creating-plugins.md)

88
docs/custom-resolvers/plugins/builtin-plugins.md
View File

@ -1,88 +0,0 @@
# Built-in Plugins
## Overview
The Custom Resolver system includes several built-in plugins that implement common resolution strategies. These can be used directly or as examples for creating custom plugins.
## Available Plugins
### Last Write Wins
Keeps the most recent value based on timestamp.
```typescript
const resolver = new CustomResolver(view, {
myProperty: new LastWriteWinsPlugin()
});
```
### First Write Wins
Keeps the first non-null value seen.
```typescript
const resolver = new CustomResolver(view, {
myProperty: new FirstWriteWinsPlugin()
});
```
### Concatenation
Combines string values with a separator.
```typescript
const resolver = new CustomResolver(view, {
fullName: new ConcatenationPlugin({
separator: ' ',
sort: true // Sort values before concatenation
})
});
```
### Majority Vote
Selects the most common value.
```typescript
const resolver = new CustomResolver(view, {
status: new MajorityVotePlugin({
minVotes: 2 // Minimum votes required to select a winner
})
});
```
### Minimum Value
Tracks the minimum numeric value.
```typescript
const resolver = new CustomResolver(view, {
minPrice: new MinPlugin()
});
```
### Maximum Value
Tracks the maximum numeric value.
```typescript
const resolver = new CustomResolver(view, {
maxScore: new MaxPlugin()
});
```
## Plugin Options
| Plugin | Options | Default | Description |
|--------|---------|---------|-------------|
| `ConcatenationPlugin` | `separator: string`<br>`sort: boolean` | `', '`<br>`false` | Separator between values and whether to sort |
| `MajorityVotePlugin` | `minVotes: number` | `1` | Minimum votes needed to select a winner |
| `LastWriteWins`<br>`FirstWriteWins`<br>`MinPlugin`<br>`MaxPlugin` | None | N/A | No configuration options |
## Choosing the Right Plugin
- Use `LastWriteWins` for simple timestamp-based resolution
- Use `FirstWriteWins` to preserve the initial value
- Use `ConcatenationPlugin` for combining string values
- Use `MajorityVote` for consensus-based resolution
- Use `MinPlugin`/`MaxPlugin` for numeric ranges

120
docs/custom-resolvers/plugins/creating-plugins.md
View File

@ -1,120 +0,0 @@
# Creating Custom Plugins
## Overview
Custom plugins allow you to implement custom resolution logic for your specific use case. This guide walks through creating a new plugin from scratch.
## Basic Plugin Structure
A minimal plugin must implement the `ResolverPlugin` interface:
```typescript
import { ResolverPlugin } from '../resolver';
class MyPlugin implements ResolverPlugin<MyState> {
initialize(): MyState {
// Return initial state
return { /* ... */ };
}
update(
currentState: MyState,
newValue: unknown,
delta: CollapsedDelta,
dependencies: {}
): MyState {
// Update state based on new value
return { /* updated state */ };
}
resolve(state: MyState): unknown {
// Return the resolved value
return /* resolved value */;
}
}
```
## Adding Dependencies
To depend on other properties, specify the dependency types:
```typescript
class DiscountedPricePlugin implements ResolverPlugin<DiscountState, 'basePrice' | 'discount'> {
readonly dependencies = ['basePrice', 'discount'] as const;
initialize(): DiscountState {
return { finalPrice: 0 };
}
update(
state: DiscountState,
_newValue: unknown,
_delta: CollapsedDelta,
deps: DependencyStates
): DiscountState {
const basePrice = deps.basePrice as number;
const discount = deps.discount as number;
return { finalPrice: basePrice * (1 - discount) };
}
resolve(state: DiscountState): number {
return state.finalPrice;
}
}
```
## Best Practices
1. **Immutable State**: Always return new state objects instead of mutating
2. **Pure Functions**: Keep update and resolve methods pure and side-effect free
3. **Error Handling**: Handle unexpected input gracefully
4. **Type Safety**: Use TypeScript types to catch errors early
5. **Documentation**: Document your plugin's behavior and requirements
## Testing Your Plugin
Create tests to verify your plugin's behavior:
```typescript
describe('DiscountedPricePlugin', () => {
let view: LosslessView;
let resolver: CustomResolver;
beforeEach(() => {
view = new LosslessView();
resolver = new CustomResolver(view, {
basePrice: new LastWriteWinsPlugin(),
discount: new LastWriteWinsPlugin(),
finalPrice: new DiscountedPricePlugin()
});
});
test('applies discount to base price', () => {
// Test your plugin's behavior
});
});
```
## Advanced Topics
### Handling Complex Dependencies
For plugins with complex dependency requirements, you can use the `dependencies` array to declare all required properties and access them in a type-safe way through the `dependencies` parameter.
### Performance Considerations
- Keep state updates minimal and efficient
- Avoid expensive computations in the update method
- Consider memoization for expensive resolve operations
### Debugging
Add logging to track state changes and resolution:
```typescript
update(currentState: MyState, newValue: unknown): MyState {
debug('Updating with:', { currentState, newValue });
// ...
}
```

30
docs/custom-resolvers/plugins/index.md
View File

@ -1,30 +0,0 @@
# Resolver Plugins
## Overview
Resolver plugins implement the core resolution logic for properties in the Custom Resolver system. Each plugin is responsible for:
1. Initializing its internal state
2. Processing updates to the property
3. Resolving the final value from the current state
## Plugin Lifecycle
1. **Initialization**: When a resolver is created, each plugin's `initialize()` method is called to set up its initial state.
2. **Update Processing**: For each new delta, the `update()` method is called with the current state, new value, and any dependency states.
3. **Resolution**: The `resolve()` method is called to produce the final value from the current state.
## Built-in Plugins
The system includes several common resolution strategies:
- [Last Write Wins](./builtin-plugins.md#last-write-wins)
- [First Write Wins](./builtin-plugins.md#first-write-wins)
- [Concatenation](./builtin-plugins.md#concatenation)
- [Majority Vote](./builtin-plugins.md#majority-vote)
- [Minimum Value](./builtin-plugins.md#min)
- [Maximum Value](./builtin-plugins.md#max)
## Creating Custom Plugins
See the [Creating Custom Plugins](./creating-plugins.md) guide for detailed information on implementing your own resolver plugins.

4
docs/schema-validation.md
View File

@ -60,12 +60,12 @@ node.lossless.ingestDelta(unsafeDelta);
// 5. Check validation status after the fact
const stats = collection.getValidationStats();
debug(`Valid: ${stats.validEntities}, Invalid: ${stats.invalidEntities}`);
console.log(`Valid: ${stats.validEntities}, Invalid: ${stats.invalidEntities}`);
// Get details about invalid entities
const invalidUsers = collection.getInvalidEntities();
invalidUsers.forEach(user => {
debug(`User ${user.entityId} is invalid:`, user.errors);
console.log(`User ${user.entityId} is invalid:`, user.errors);
});
```

100
docs/test-helpers.md
View File

@ -1,100 +0,0 @@
# Test Helpers
This document provides documentation for the test helper functions available in the Rhizome Node test suite.
## `testResolverWithPlugins`
A helper function for testing custom resolvers with plugins and a sequence of deltas.
### Import
```typescript
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
```
### Signature
```typescript
function testResolverWithPlugins<T>({
entityId,
plugins,
deltas,
expectedResult
}: {
entityId: string;
plugins: Record<string, ResolverPlugin>;
deltas: Delta[];
expectedResult: (result: T) => void;
}): Promise<void>;
```
### Parameters
- `entityId`: The ID of the entity to test
- `plugins`: An object mapping property names to their respective resolver plugins
- `deltas`: An array of `Delta` objects to process
- `expectedResult`: A callback function that receives the resolved result for assertions
### Return Value
A promise that resolves when the test is complete.
### Example Usage
```typescript
import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
import { ConcatenationPlugin } from '@src/views/resolvers/custom-resolvers/builtin-plugins';
describe('MyCustomResolver', () => {
test('should process deltas correctly', async () => {
// Run test with plugins and deltas
await testResolverWithPlugins({
entityId: 'entity1',
plugins: {
myProperty: new ConcatenationPlugin()
},
deltas: [
createTestDelta('user1', 'host1')
.setProperty('entity1', 'myProperty', 'value1')
.buildV1(),
createTestDelta('user1', 'host1')
.setProperty('entity1', 'myProperty', 'value2')
.buildV1()
],
expectedResult: (result) => {
expect(result.properties.myProperty).toBe('value1 value2');
}
});
});
});
```
## `createTestDelta`
A helper function for creating test deltas with a fluent API.
### Example Usage
```typescript
const delta = createTestDelta('user1', 'host1')
.withTimestamp(1000)
.setProperty('entity1', 'tags', 'red', 'color1')
.buildV1();
```
## How It Works
1. Creates a new `Lossless` instance for the test
2. Sets up a `CustomResolver` with the provided plugins
3. Ingests all provided deltas into the `Lossless` instance
4. Retrieves a view for the specified entity
5. Processes the view through the resolver
6. Calls the `expectedResult` callback with the resolved entity
## Best Practices
- Use this helper when testing custom resolvers with plugins
- The helper handles all setup and teardown of test resources
- Use `createTestDelta` for consistent delta creation in tests
- The helper ensures type safety between the resolver and the expected result type
- Each test gets a fresh `Lossless` instance automatically

2
examples/app.ts
View File

@ -1,6 +1,6 @@
import Debug from 'debug';
import {BasicCollection, Entity, RhizomeNode} from '../src';
const debug = Debug('rz:example-app');
const debug = Debug('example-app');
// As an app we want to be able to write and read data.
// The data is whatever shape we define it to be in a given context.

8
examples/json-ast.ts
View File

@ -29,9 +29,9 @@ const ast = jsonToAst(exampleJson, {
// filter: (node) => !node.path || node.path.includes('address')
});
debug("Original JSON:", JSON.stringify(exampleJson, null, 2));
console.log("Original JSON:", JSON.stringify(exampleJson, null, 2));
debug("\nAST:", JSON.stringify(ast, null, 2));
console.log("\nAST:", JSON.stringify(ast, null, 2));
// Example of traversing the AST
function traverse(node: any, indent = 0) {
@ -40,12 +40,12 @@ function traverse(node: any, indent = 0) {
const value = node.value !== undefined ? `: ${JSON.stringify(node.value)}` : '';
const path = node.path ? ` [${node.path}]` : '';
debug(`${padding}${type}${value}${path}`);
console.log(`${padding}${type}${value}${path}`);
if (node.children) {
node.children.forEach((child: any) => traverse(child, indent + 2));
}
}
debug('\nTraversed AST:');
console.log('\nTraversed AST:');
traverse(ast);

13
package-lock.json generated
View File

@ -12,7 +12,6 @@
"@types/dockerode": "^3.3.40",
"debug": "^4.4.0",
"dockerode": "^4.0.7",
"dotenv": "^16.5.0",
"express": "^4.21.2",
"json-logic-js": "^2.0.5",
"level": "^9.0.0",
@ -4361,18 +4360,6 @@
"node": ">=0.10.0"
}
},
"node_modules/dotenv": {
"version": "16.5.0",
"resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.5.0.tgz",
"integrity": "sha512-m/C+AwOAr9/W1UOIZUo232ejMNnJAJtYQjUbHoNTBNTJSvqzzDh7vnrei3o3r3m9blf6ZoDkvcw0VmozNRFJxg==",
"license": "BSD-2-Clause",
"engines": {
"node": ">=12"
},
"funding": {
"url": "https://dotenvx.com"
}
},
"node_modules/dunder-proto": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.0.tgz",

9
package.json
View File

@ -27,10 +27,7 @@
"/dist/"
],
"moduleNameMapper": {
"^@src$": "<rootDir>/src",
"^@src/(.*)$": "<rootDir>/src/$1",
"^@test-helpers$": "<rootDir>/__tests__/__helpers__",
"^@test-helpers/(.*)$": "<rootDir>/__tests__/__helpers__/$1"
"^@/(.*)$": "<rootDir>/src/$1"
},
"transform": {
"^\\.tsx?$": [
@ -40,9 +37,6 @@
}
]
},
"setupFiles": [
"./__tests__/jest-setup.ts"
],
"detectOpenHandles": true,
"forceExit": true,
"verbose": true,
@ -65,7 +59,6 @@
"@types/dockerode": "^3.3.40",
"debug": "^4.4.0",
"dockerode": "^4.0.7",
"dotenv": "^16.5.0",
"express": "^4.21.2",
"json-logic-js": "^2.0.5",
"level": "^9.0.0",

0
__plans__/README.md → plans/README.md
View File

0
__plans__/beam-implementation.md → plans/beam-implementation.md
View File

0
__plans__/dimensions.md → plans/dimensions.md
View File

0
__plans__/ent-rel-graph.md → plans/ent-rel-graph.md
View File

8
plans/housekeeping.md Normal file
View File

@ -0,0 +1,8 @@
# Housekeeping tasks
- [x] Organize tests?
- [ ] More documentation in docs/
- [ ] Rename/consolidate, lossless view() and compose() --> composeView()
- [ ] Rename Lossless to HyperView
- [ ] Rename Lossy to View
- [ ] Consider whether we should use collapsed deltas

152
plans/plugin-dep-vis.md Normal file
View File

@ -0,0 +1,152 @@
# Plugin Dependency Visibility Implementation Plan
## Overview
This document outlines the implementation plan for enforcing restricted state visibility in the CustomResolver system. The goal is to ensure that each plugin can only access the states of properties it has explicitly declared as dependencies.
## Current Behavior
- All plugins currently receive the complete `allStates` object containing all property states
- There's no enforcement of which states a plugin can access
- Dependencies are declared but not used for access control
## Proposed Changes
### 1. Update ResolverPlugin Interface
```typescript
interface ResolverPlugin<T = unknown> {
name: string;
dependencies?: PropertyID[]; // Explicitly declare which properties this plugin depends on
// ... rest of the interface
}
```
### 2. Modify CustomResolver Implementation
#### 2.1 Update Reducer Method
Modify the `reducer` method to filter states before passing to plugins:
```typescript
public reducer(
acc: CustomResolverAccumulator,
cur: LosslessViewOne
): CustomResolverAccumulator {
// ... existing setup code ...
// Process each property in execution order
for (const propertyId of executionOrder) {
// ... existing delta processing ...
// Create filtered states object with only declared dependencies
const visibleStates: Record<PropertyID, unknown> = {};
// Add states for declared dependencies
if (plugin.dependencies) {
for (const dep of plugin.dependencies) {
if (allStates[dep] !== undefined) {
visibleStates[dep] = allStates[dep];
}
}
}
// Pass only visible states to the plugin
propertyState.state = propertyState.plugin.update(
propertyState.state,
value,
delta,
visibleStates
);
// ... rest of the method ...
}
}
```
#### 2.2 Update Resolver Method
Similarly update the `resolver` method:
```typescript
resolver(cur: CustomResolverAccumulator): CustomResolverResult {
const res: CustomResolverResult = {};
for (const [entityId, entity] of Object.entries(cur)) {
const entityResult = { id: entityId, properties: {} };
const allStates: Record<PropertyID, unknown> = {};
// First pass: collect all states
for (const [propId, propState] of Object.entries(entity.properties)) {
allStates[propId] = propState.state;
}
// Second pass: resolve each property with filtered states
for (const [propId, propState] of Object.entries(entity.properties)) {
const plugin = propState.plugin;
const visibleStates: Record<PropertyID, unknown> = {};
// Only include declared dependencies
if (plugin.dependencies) {
for (const dep of plugin.dependencies) {
if (allStates[dep] !== undefined) {
visibleStates[dep] = allStates[dep];
}
}
}
const resolvedValue = plugin.resolve(propState.state, visibleStates);
if (resolvedValue !== undefined) {
entityResult.properties[propId] = resolvedValue;
}
}
if (Object.keys(entityResult.properties).length > 0) {
res[entityId] = entityResult;
}
}
return res;
}
```
### 3. Add Validation
Add validation to ensure dependencies exist:
```typescript
private validateDependencies(): void {
// Existing cycle detection...
// Add validation that all dependencies exist
for (const [pluginId, plugin] of Object.entries(this.config)) {
for (const dep of plugin.dependencies || []) {
if (!this.config[dep]) {
throw new Error(`Plugin '${pluginId}' depends on unknown property: ${dep}`);
}
}
}
}
```
### 4. Update Tests
1. Add tests for state visibility:
- Test that plugins only receive their declared dependencies
- Test that plugins can't access undeclared dependencies
- Test that dependency validation works
- Test that existing functionality remains unchanged
2. Update existing tests to account for the new behavior
## Migration Strategy
1. This is a breaking change for any plugins that were accessing undeclared dependencies
2. Add warnings in the next minor version
3. Make the behavior opt-in initially with a flag
4. In the next major version, make it the default
## Implementation Steps
1. [ ] Add the state filtering to `reducer`
2. [ ] Add the state filtering to `resolver`
3. [ ] Update dependency validation
4. [ ] Add comprehensive tests
5. [ ] Update documentation
6. [ ] Add deprecation warnings for plugins accessing undeclared dependencies
## Future Considerations
1. Add a debug mode that logs when plugins access undeclared dependencies
2. Consider adding granular permissions (read/write) for dependencies
3. Add support for wildcard dependencies for plugins that need access to many properties

11
scripts/find_duplicate_tests
View File

@ -1,11 +0,0 @@
#!/bin/env bash
DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
${DIR}/list_tests |
sort |
uniq -d |
while read title; do
grep -Rn --color "$title" __tests__
echo
done

7
scripts/list_tests
View File

@ -1,7 +0,0 @@
#!/bin/env bash
DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
find "${DIR}/../__tests__" -name "*.test.ts" |
xargs grep "test(" |
sed "s/^.*[\"']\([^\"']\+\)[\"'].*$/\1/"

11
src/collections/collection-abstract.ts
View File

@ -4,16 +4,11 @@ import EventEmitter from "node:events";
import {Delta} from "../core/delta";
import {createDelta} from "../core/delta-builder";
import {Entity, EntityProperties} from "../core/entity";
import { ResolvedTimestampedViewOne as ResolvedViewOne } from '../views/resolvers/timestamp-resolvers';
import {RhizomeNode} from "../node";
import {DomainEntityID} from "../core/types";
import { ResolvedTimestampedViewOne } from '../views/resolvers/timestamp-resolvers';
const debug = Debug('rz:abstract-collection');
type CollectionEntity = {
id: DomainEntityID;
properties: EntityProperties;
}
export abstract class Collection<View> {
rhizomeNode?: RhizomeNode;
name: string;
@ -26,7 +21,7 @@ export abstract class Collection<View> {
abstract initializeView(): void;
abstract resolve(id: DomainEntityID): ResolvedTimestampedViewOne | undefined;
abstract resolve(id: DomainEntityID): ResolvedViewOne | undefined;
rhizomeConnect(rhizomeNode: RhizomeNode) {
this.rhizomeNode = rhizomeNode;
@ -136,7 +131,7 @@ export abstract class Collection<View> {
async put(
entityId: DomainEntityID | undefined,
properties: EntityProperties,
): Promise<CollectionEntity> {
): Promise<ResolvedViewOne> {
if (!this.rhizomeNode) throw new Error('collection not connecte to rhizome');
// For convenience, we allow setting id via properties.id

3
src/collections/collection-basic.ts
View File

@ -4,6 +4,7 @@
// It could then be further extended with e.g. table semantics like filter, sort, join
import {Collection} from '../collections/collection-abstract';
import { ResolvedTimestampedViewOne as ResolvedViewOne } from '../views/resolvers/timestamp-resolvers';
import {TimestampResolver} from '../views/resolvers/timestamp-resolvers';
export class BasicCollection extends Collection<TimestampResolver> {
@ -16,7 +17,7 @@ export class BasicCollection extends Collection<TimestampResolver> {
resolve(
id: string
) {
): ResolvedViewOne | undefined {
if (!this.rhizomeNode) throw new Error('collection not connected to rhizome');
if (!this.lossy) throw new Error('lossy view not initialized');

8
src/collections/collection-typed.ts
View File

@ -102,7 +102,7 @@ export class TypedCollectionImpl<T extends Record<string, unknown>>
getValidatedView(entityId: DomainEntityID): SchemaAppliedView | undefined {
if (!this.rhizomeNode) throw new Error('collection not connected to rhizome');
const losslessView = this.rhizomeNode.lossless.compose([entityId])[entityId];
const losslessView = this.rhizomeNode.lossless.view([entityId])[entityId];
if (!losslessView) return undefined;
return this.apply(losslessView);
@ -173,7 +173,7 @@ export class TypedCollectionImpl<T extends Record<string, unknown>>
for (const entityId of entityIds) {
if (!this.rhizomeNode) continue;
const losslessView = this.rhizomeNode.lossless.compose([entityId])[entityId];
const losslessView = this.rhizomeNode.lossless.view([entityId])[entityId];
if (!losslessView) continue;
const validationResult = this.schemaRegistry.validate(entityId, this.schema.id, losslessView);
@ -203,7 +203,7 @@ export class TypedCollectionImpl<T extends Record<string, unknown>>
if (!this.rhizomeNode) return [];
return this.getIds().filter(entityId => {
const losslessView = this.rhizomeNode!.lossless.compose([entityId])[entityId];
const losslessView = this.rhizomeNode!.lossless.view([entityId])[entityId];
if (!losslessView) return false;
const validationResult = this.schemaRegistry.validate(entityId, this.schema.id, losslessView);
@ -217,7 +217,7 @@ export class TypedCollectionImpl<T extends Record<string, unknown>>
const invalid: Array<{ entityId: DomainEntityID; errors: string[] }> = [];
for (const entityId of this.getIds()) {
const losslessView = this.rhizomeNode.lossless.compose([entityId])[entityId];
const losslessView = this.rhizomeNode.lossless.view([entityId])[entityId];
if (!losslessView) continue;
const validationResult = this.schemaRegistry.validate(entityId, this.schema.id, losslessView);

4
src/config.ts
View File

@ -1,6 +1,4 @@
import {randomUUID} from "crypto";
import dotenv from 'dotenv';
dotenv.config();
// _HOST refers to the address from an external perspective
// _ADDR refers to the interface address from the service's perspective
@ -27,5 +25,3 @@ export const HTTP_API_PORT = parseInt(process.env.RHIZOME_HTTP_API_PORT || '3000
export const HTTP_API_ENABLE = process.env.RHIZOME_HTTP_API_ENABLE === 'true';
export const PUB_SUB_TOPIC = process.env.RHIZOME_PUB_SUB_TOPIC || `deltas-${randomUUID()}`;
export const DOCKER_ENABLE = process.env.RHIZOME_DOCKER_ENABLE === 'true';

22
src/core/delta-builder.ts
View File

@ -1,7 +1,7 @@
import { DeltaV1, DeltaV2 } from './delta';
import { randomUUID } from 'crypto';
import { PropertyTypes } from './types';
import { PointersV2 } from './delta';
import Debug from 'debug';
const debug = Debug('rz:delta-builder');
/**
* A fluent builder for creating Delta objects with proper validation and type safety.
@ -12,7 +12,7 @@ export class DeltaBuilder {
private timeCreated?: number;
private host: string;
private creator: string;
private pointers: PointersV2 = {};
private pointers: Record<string, any> = {};
/**
* Create a new DeltaBuilder instance
@ -75,23 +75,19 @@ export class DeltaBuilder {
* @param targetContext Optional target context for the pointer
*/
addPointer(localContext: string, target: string | number | boolean | null, targetContext?: string): this {
const pointerTarget = (targetContext && typeof target === 'string')
? { [target]: targetContext } : target;
if (this.pointers[localContext] &&
JSON.stringify(this.pointers[localContext]) !== JSON.stringify(pointerTarget)
) {
throw new Error(`Pointer for ${localContext} already exists with different value`);
if (targetContext && typeof target === 'string') {
this.pointers[localContext] = { [target]: targetContext };
} else {
this.pointers[localContext] = target;
}
this.pointers[localContext] = pointerTarget;
return this;
}
/**
* Set a property on an entity
* ! Note that the way we are doing this is awkward/problematic for deltas that set multiple properties.
* ! entityLabel and property each need to be unique within a given delta
*/
setProperty(entityId: string, property: string, value: string | number | boolean | null, entityLabel = "entity"): this {
// Note that entityLabe and property each need to be unique within a given delta
this.addPointer(entityLabel, entityId, property)
this.addPointer(property, value);
return this;
@ -104,7 +100,7 @@ export class DeltaBuilder {
* @param relationship The type of relationship
* @param properties Optional properties for the relationship
*/
relate(sourceId: string, targetId: string, relationship: string, properties?: Record<string, PropertyTypes>): this {
relate(sourceId: string, targetId: string, relationship: string, properties?: Record<string, any>): this {
const relId = randomUUID();
this.setProperty(relId, 'source', sourceId, '_rel_source');
this.setProperty(relId, 'target', targetId, '_rel_target');

5
src/core/entity.ts
View File

@ -13,11 +13,6 @@ export type EntityProperties = {
[key: string]: PropertyTypes;
};
export type EntityRecord = {
id: string;
properties: EntityProperties;
};
export class Entity {
properties: EntityProperties = {};
ahead = 0;

4
src/http/api.ts
View File

@ -135,7 +135,7 @@ export class HttpApi {
// View a single transaction
this.router.get('/transaction/:id', (req: express.Request, res: express.Response) => {
const {params: {id}} = req;
const v = this.rhizomeNode.lossless.compose([id]);
const v = this.rhizomeNode.lossless.view([id]);
const ent = v[id];
if (!ent.referencedAs.includes("_transaction")) {
res.status(400).json({error: "Entity is not a transaction", id});
@ -151,7 +151,7 @@ export class HttpApi {
// Get a lossless view of a single domain entity
this.router.get('/lossless/:id', (req: express.Request, res: express.Response) => {
const {params: {id}} = req;
const v = this.rhizomeNode.lossless.compose([id]);
const v = this.rhizomeNode.lossless.view([id]);
const ent = v[id];
res.json({

3
src/orchestration/test-orchestrator/index.ts
View File

@ -169,11 +169,13 @@ export class TestOrchestrator extends BaseOrchestrator {
// In a real implementation, we would connect the nodes here
// For testing, we'll just log the connection attempt
console.log(`Connecting nodes ${node1.id} and ${node2.id}`);
}
async partitionNetwork(partitions: NetworkPartition): Promise<void> {
// In a real implementation, we would create network partitions
// For testing, we'll just log the partition attempt
console.log('Creating network partitions:', partitions);
}
async setResourceLimits(
@ -181,6 +183,7 @@ export class TestOrchestrator extends BaseOrchestrator {
limits: Partial<NodeConfig['resources']>
): Promise<void> {
// In-memory nodes don't have real resource limits
console.log(`Setting resource limits for ${handle.id}:`, limits);
}
/**

8
src/schema/schema-registry.ts
View File

@ -478,7 +478,7 @@ export class DefaultSchemaRegistry implements SchemaRegistry {
for (const referenceId of referenceIds) {
try {
// Get the referenced entity's lossless view
const referencedViews = losslessView.compose([referenceId]);
const referencedViews = losslessView.view([referenceId]);
const referencedView = referencedViews[referenceId];
if (referencedView) {
@ -534,7 +534,7 @@ export class DefaultSchemaRegistry implements SchemaRegistry {
// Count entity references vs scalars
if (typeof target === 'string') {
const referencedViews = losslessView.compose([target]);
const referencedViews = losslessView.view([target]);
if (referencedViews[target]) {
entityReferenceCount++;
} else {
@ -567,7 +567,7 @@ export class DefaultSchemaRegistry implements SchemaRegistry {
if (typeof target === 'string') {
// Try to resolve as entity reference
try {
const referencedViews = losslessView.compose([target]);
const referencedViews = losslessView.view([target]);
const referencedView = referencedViews[target];
if (referencedView) {
@ -600,7 +600,7 @@ export class DefaultSchemaRegistry implements SchemaRegistry {
if (typeof target === 'string') {
// Try to resolve as entity reference
try {
const referencedViews = losslessView.compose([target]);
const referencedViews = losslessView.view([target]);
const referencedView = referencedViews[target];
if (referencedView) {

22
src/utils/json-ast/index.ts
View File

@ -19,7 +19,7 @@ export function jsonToAst(
// Handle max depth
if (depth > maxDepth) {
return {
type: typeof json === 'object' && json !== null ? 'object' : typeof json as 'string' | 'number' | 'boolean' | 'object',
type: typeof json === 'object' && json !== null ? 'object' : typeof json as any,
value: '[Max depth exceeded]',
...(includePath && currentPath ? { path: currentPath } : {})
};
@ -83,7 +83,7 @@ export function jsonToAst(
*/
function createNode(
type: JsonNode['type'],
value: JsonValue,
value: any,
path: string = '',
includePath: boolean = true
): JsonNode {
@ -94,3 +94,21 @@ function createNode(
return node;
}
/**
* Example usage of the JSON to AST converter
*/
function exampleUsage() {
const exampleJson = {
name: "John",
age: 30,
active: true,
tags: ["admin", "user"],
address: {
street: "123 Main St",
city: "Anytown"
}
};
const ast = jsonToAst(exampleJson, { includePath: true });
console.log(JSON.stringify(ast, null, 2));
}

24
src/views/lossless.ts
View File

@ -179,6 +179,18 @@ export class Lossless {
return transactionId;
}
viewSpecific(entityId: DomainEntityID, deltaIds: DeltaID[], deltaFilter?: DeltaFilter): LosslessViewOne | undefined {
const combinedFilter = (delta: Delta) => {
if (!deltaIds.includes(delta.id)) {
return false;
}
if (!deltaFilter) return true;
return deltaFilter(delta);
};
const res = this.compose([entityId], (delta) => combinedFilter(delta));
return res[entityId];
}
decompose(view: LosslessViewOne): Delta[] {
const allDeltas: Delta[] = [];
const seenDeltaIds = new Set<DeltaID>();
@ -224,6 +236,11 @@ export class Lossless {
return allDeltas;
}
// Backward compatibility alias
view(entityIds?: DomainEntityID[], deltaFilter?: DeltaFilter): LosslessViewMany {
return this.compose(entityIds, deltaFilter);
}
compose(entityIds?: DomainEntityID[], deltaFilter?: DeltaFilter): LosslessViewMany {
const view: LosslessViewMany = {};
entityIds = entityIds ?? Array.from(this.domainEntities.keys());
@ -241,7 +258,6 @@ export class Lossless {
let hasVisibleDeltas = false;
// First, collect all deltas for this entity to properly apply negations
// TODO: This is very inefficient. We need a better algorithm for applying negations.
const allEntityDeltas: Delta[] = [];
for (const deltas of ent.properties.values()) {
allEntityDeltas.push(...Array.from(deltas));
@ -272,11 +288,7 @@ export class Lossless {
const pointers: CollapsedPointer[] = [];
for (const {localContext, target, targetContext} of delta.pointers) {
if (targetContext) {
// Only store primitive pointers in the collapsed delta
continue;
}
for (const {localContext, target} of delta.pointers) {
pointers.push({[localContext]: target});
if (target === ent.id) {
referencedAs.add(localContext);

66
src/views/lossy.ts
View File

@ -3,7 +3,7 @@
// into various possible "lossy" views that combine or exclude some information.
import Debug from 'debug';
import {Delta, DeltaFilter, DeltaID} from "../core/delta";
import {DeltaFilter, DeltaID} from "../core/delta";
import {Lossless, LosslessViewOne} from "./lossless";
import {DomainEntityID, PropertyID, PropertyTypes, ViewMany} from "../core/types";
const debug = Debug('rz:lossy');
@ -18,13 +18,13 @@ export type LossyViewOne<T = PropertyMap> = {
export type LossyViewMany<T = PropertyMap> = ViewMany<LossyViewOne<T>>;
// We support incremental updates of lossy models.
export abstract class Lossy<Accumulator, Result = Accumulator> {
export abstract class Lossy<Accumulator, Result> {
deltaFilter?: DeltaFilter;
private accumulator?: Accumulator;
accumulator?: Accumulator;
initializer?(): Accumulator;
abstract initializer(v: LosslessViewOne): Accumulator;
abstract reducer(acc: Accumulator, cur: LosslessViewOne): Accumulator;
resolver?(acc: Accumulator, entityIds: DomainEntityID[]): Result;
abstract resolver(cur: Accumulator): Result;
constructor(
readonly lossless: Lossless,
@ -35,44 +35,50 @@ export abstract class Lossy<Accumulator, Result = Accumulator> {
this.ingestUpdate(id, deltaIds);
});
debug(`Lossy view initialized: ${this.constructor.name}`);
}
ingestUpdate(entityId: DomainEntityID, deltaIds: DeltaID[]) {
const combinedFilter = (delta: Delta) => {
if (!deltaIds.includes(delta.id)) {
return false;
}
if (!this.deltaFilter) return true;
return this.deltaFilter(delta);
};
const losslessPartial = this.lossless.compose([entityId], combinedFilter);
ingestUpdate(id: DomainEntityID, deltaIds: DeltaID[]) {
const losslessPartial = this.lossless.viewSpecific(id, deltaIds, this.deltaFilter);
if (!losslessPartial) {
// This should not happen; this should only be called after the lossless view has been updated
console.error(`Lossless view for entity ${entityId} not found`);
return;
}
const latest = this.accumulator || this.initializer?.() || {} as Accumulator;
this.accumulator = this.reducer(latest, losslessPartial[entityId]);
if (!losslessPartial) return;
const latest = this.accumulator || this.initializer(losslessPartial);
this.accumulator = this.reducer(latest, losslessPartial);
}
// Using the lossless view of some given domain entities,
// apply a filter to the deltas composing that lossless view,
// and then apply a supplied resolver function which receives
// the filtered lossless view as input.
// Resolve the current state of the view
resolve(entityIds?: DomainEntityID[]): Result | undefined {
if (!this.accumulator) {
return undefined;
}
if (!entityIds) {
entityIds = Array.from(this.lossless.domainEntities.keys());
}
if (!this.resolver) {
throw new Error(`Resolver not implemented for ${this.constructor.name}`)
// If we don't have an accumulator, build it from the lossless view
if (!this.accumulator) {
this.accumulator = {} as Accumulator;
// Use the general view method to get the full view
const fullView = this.lossless.view(entityIds, this.deltaFilter);
// Build the accumulator by reducing each entity's view
for (const entityId of entityIds) {
const losslessViewOne = fullView[entityId];
if (losslessViewOne) {
if (!this.accumulator) {
this.accumulator = this.initializer(losslessViewOne);
} else {
this.accumulator = this.reducer(this.accumulator, losslessViewOne);
}
}
}
}
return this.resolver(this.accumulator, entityIds);
if (!this.accumulator) return undefined;
return this.resolver(this.accumulator);
}
}

58
src/views/resolvers/aggregation-resolvers.ts
View File

@ -1,3 +1,4 @@
import { EntityProperties } from "../../core/entity";
import { Lossless, LosslessViewOne } from "../lossless";
import { Lossy } from '../lossy';
import { DomainEntityID, PropertyID, ViewMany } from "../../core/types";
@ -26,7 +27,15 @@ export type AggregatedViewOne = {
export type AggregatedViewMany = ViewMany<AggregatedViewOne>;
type ResolvedAggregatedViewOne = {
id: DomainEntityID;
properties: EntityProperties;
};
type ResolvedAggregatedViewMany = ViewMany<ResolvedAggregatedViewOne>;
type Accumulator = AggregatedViewMany;
type Result = ResolvedAggregatedViewMany;
// Extract a particular value from a delta's pointers
export function valueFromCollapsedDelta(
@ -42,7 +51,26 @@ export function valueFromCollapsedDelta(
}
}
export class AggregationResolver extends Lossy<Accumulator> {
function aggregateValues(values: number[], type: AggregationType): number {
if (values.length === 0) return 0;
switch (type) {
case 'min':
return Math.min(...values);
case 'max':
return Math.max(...values);
case 'sum':
return values.reduce((sum, val) => sum + val, 0);
case 'average':
return values.reduce((sum, val) => sum + val, 0) / values.length;
case 'count':
return values.length;
default:
throw new Error(`Unknown aggregation type: ${type}`);
}
}
export class AggregationResolver extends Lossy<Accumulator, Result> {
constructor(
lossless: Lossless,
private config: AggregationConfig
@ -50,6 +78,12 @@ export class AggregationResolver extends Lossy<Accumulator> {
super(lossless);
}
initializer(view: LosslessViewOne): Accumulator {
return {
[view.id]: { id: view.id, properties: {} }
};
}
reducer(acc: Accumulator, cur: LosslessViewOne): Accumulator {
if (!acc[cur.id]) {
acc[cur.id] = { id: cur.id, properties: {} };
@ -81,6 +115,28 @@ export class AggregationResolver extends Lossy<Accumulator> {
return acc;
}
resolver(cur: Accumulator): Result {
const res: Result = {};
for (const [id, entity] of Object.entries(cur)) {
const entityResult: ResolvedAggregatedViewOne = { id, properties: {} };
for (const [propertyId, aggregatedProp] of Object.entries(entity.properties)) {
const result = aggregateValues(aggregatedProp.values, aggregatedProp.type);
entityResult.properties[propertyId] = result;
}
// Only include entities that have at least one aggregated property
if (Object.keys(entityResult.properties).length > 0) {
res[id] = entityResult;
}
}
return res;
}
}
// Convenience classes for common aggregation types

55
src/views/resolvers/custom-resolvers/plugin.ts
View File

@ -2,71 +2,44 @@ import { PropertyID, PropertyTypes } from "../../../core/types";
import { CollapsedDelta } from "../../lossless";
/**
* Type representing a mapping of dependency names to their state types
* Plugin interface for custom resolvers
*/
// export type DependencyStates = {
// [K in D]: unknown;
// };
export type DependencyStates = Record<string, unknown>;
/**
* Plugin interface for custom resolvers with type-safe dependencies
* @template T - Type of the plugin's internal state
* @template D - Union type of dependency names (e.g., 'discount' | 'tax')
*/
export abstract class ResolverPlugin<
T = unknown,
D extends string = never
> {
name?: PropertyID;
export interface ResolverPlugin<T = unknown> {
name: string;
/**
* Array of property IDs that this plugin depends on.
* The plugins corresponding to these properties will be processed before this plugin.
* These properties will be processed before this plugin.
*/
dependencies?: readonly D[];
dependencies?: PropertyID[];
/**
* Initialize the state for a property
*/
abstract initialize(
dependencies: DependencyStates
): T;
initialize(): T;
/**
* Process a new value for the property
*/
abstract update(
update(
currentState: T,
newValue?: PropertyTypes,
delta?: CollapsedDelta,
dependencies?: DependencyStates
newValue: PropertyTypes,
delta: CollapsedDelta,
allStates?: Record<PropertyID, unknown>
): T;
/**
* Resolve the final value from the accumulated state
*/
abstract resolve(
resolve(
state: T,
dependencies: DependencyStates
allStates?: Record<PropertyID, unknown>
): PropertyTypes | undefined;
}
/**
* Configuration for custom resolver with type-safe plugin configurations
* Configuration for custom resolver
*/
export type CustomResolverConfig = {
[P in PropertyID]: ResolverPlugin<unknown, string>;
[propertyId: PropertyID]: ResolverPlugin;
};
/**
* Helper type to extract the state type from a ResolverPlugin
*/
export type PluginState<T> = T extends ResolverPlugin<infer S, string> ? S : never;
/**
* Helper type to extract the dependency names from a ResolverPlugin
*/
export type PluginDependencies<T> = T extends ResolverPlugin<unknown, infer D> ? D : never;

34
src/views/resolvers/custom-resolvers/plugins/concatenation.plugin.ts
View File

@ -1,38 +1,29 @@
import { PropertyTypes } from "../../../../core/types";
import { CollapsedDelta } from "../../../../views/lossless";
import { CollapsedDelta } from "../../../lossless";
import { ResolverPlugin } from "../plugin";
import Debug from 'debug';
const debug = Debug('rz:concatenation-plugin');
type ConcatenationState = {
values: Array<{ value: string; timestamp: number }>;
};
/**
* Concatenation plugin (for string values)
*
* Concatenates all string values with a separator
*/
export class ConcatenationPlugin implements ResolverPlugin<ConcatenationState, never> {
readonly dependencies = [] as const;
export class ConcatenationPlugin implements ResolverPlugin<{ values: { value: string, timestamp: number }[] }> {
name = 'concatenation';
dependencies: string[] = [];
constructor(private separator: string = ' ') {}
initialize(): ConcatenationState {
initialize() {
return { values: [] };
}
update(
currentState: ConcatenationState,
newValue: PropertyTypes | null,
currentState: { values: { value: string, timestamp: number }[] },
newValue: PropertyTypes,
delta: CollapsedDelta,
): ConcatenationState {
debug(`Update, newValue: ${newValue}`);
// Skip null, undefined, or non-string values
if (newValue === null || newValue === undefined || typeof newValue !== 'string') {
return currentState;
}
_allStates?: Record<string, unknown>
) {
if (typeof newValue === 'string') {
return {
values: [
...currentState.values,
@ -40,9 +31,12 @@ export class ConcatenationPlugin implements ResolverPlugin<ConcatenationState, n
]
};
}
return currentState;
}
resolve(
state: ConcatenationState,
state: { values: { value: string, timestamp: number }[] },
_allStates?: Record<string, unknown>
): PropertyTypes {
// Sort by timestamp to ensure consistent ordering
const sortedValues = [...state.values].sort((a, b) => a.timestamp - b.timestamp);

20
src/views/resolvers/custom-resolvers/plugins/first-write-wins.plugin.ts
View File

@ -2,28 +2,25 @@ import { PropertyTypes } from "../../../../core/types";
import { CollapsedDelta } from "../../../lossless";
import { ResolverPlugin } from "../plugin";
type FirstWriteWinsState = {
value?: PropertyTypes;
timestamp: number;
};
/**
* First Write Wins plugin
*
* Keeps the first value that was written, ignoring subsequent writes
*/
export class FirstWriteWinsPlugin implements ResolverPlugin<FirstWriteWinsState, never> {
readonly dependencies = [] as const;
export class FirstWriteWinsPlugin implements ResolverPlugin<{ value?: PropertyTypes, timestamp: number }> {
name = 'first-write-wins';
dependencies: string[] = [];
initialize(): FirstWriteWinsState {
initialize() {
return { timestamp: Infinity };
}
update(
currentState: FirstWriteWinsState,
currentState: { value?: PropertyTypes, timestamp: number },
newValue: PropertyTypes,
delta: CollapsedDelta,
): FirstWriteWinsState {
_allStates?: Record<string, unknown>
) {
// Only update if this delta is earlier than our current earliest
if (delta.timeCreated < currentState.timestamp) {
return {
@ -35,7 +32,8 @@ export class FirstWriteWinsPlugin implements ResolverPlugin<FirstWriteWinsState,
}
resolve(
state: FirstWriteWinsState,
state: { value?: PropertyTypes, timestamp: number },
_allStates?: Record<string, unknown>
): PropertyTypes | undefined {
return state.value;
}

22
src/views/resolvers/custom-resolvers/plugins/last-write-wins.plugin.ts
View File

@ -1,29 +1,26 @@
import { PropertyTypes } from "../../../../core/types";
import { PropertyID, PropertyTypes } from "../../../../core/types";
import { CollapsedDelta } from "../../../lossless";
import { ResolverPlugin } from "../plugin";
type LastWriteWinsState = {
value?: PropertyTypes;
timestamp: number;
};
/**
* Last Write Wins plugin
*
* Keeps the most recent value based on the delta's timestamp
*/
export class LastWriteWinsPlugin implements ResolverPlugin<LastWriteWinsState, never> {
readonly dependencies = [] as const;
export class LastWriteWinsPlugin implements ResolverPlugin<{ value?: PropertyTypes, timestamp: number }> {
name = 'last-write-wins';
dependencies: PropertyID[] = [];
initialize(): LastWriteWinsState {
initialize() {
return { timestamp: 0 };
}
update(
currentState: LastWriteWinsState,
currentState: { value?: PropertyTypes, timestamp: number },
newValue: PropertyTypes,
delta: CollapsedDelta,
): LastWriteWinsState {
_allStates?: Record<string, unknown>
) {
if (delta.timeCreated > currentState.timestamp) {
return {
value: newValue,
@ -34,7 +31,8 @@ export class LastWriteWinsPlugin implements ResolverPlugin<LastWriteWinsState, n
}
resolve(
state: LastWriteWinsState,
state: { value?: PropertyTypes, timestamp: number },
_allStates?: Record<string, unknown>
): PropertyTypes {
return state.value || '';
}

27
src/views/resolvers/custom-resolvers/plugins/majority-vote.plugin.ts
View File

@ -1,35 +1,34 @@
import { PropertyTypes } from "../../../../core/types";
import { CollapsedDelta } from "../../../lossless";
import { ResolverPlugin } from "../plugin";
type MajorityVoteState = {
votes: Map<PropertyTypes, number>;
};
/**
* Majority vote plugin
*
* Returns the value that appears most frequently
*/
export class MajorityVotePlugin implements ResolverPlugin<MajorityVoteState, never> {
readonly dependencies = [] as const;
export class MajorityVotePlugin implements ResolverPlugin<{ votes: Map<PropertyTypes, number> }> {
name = 'majority-vote';
dependencies: string[] = [];
initialize(): MajorityVoteState {
initialize() {
return { votes: new Map<PropertyTypes, number>() };
}
update(
currentState: MajorityVoteState,
currentState: { votes: Map<PropertyTypes, number> },
newValue: PropertyTypes,
): MajorityVoteState {
_delta: CollapsedDelta,
_allStates?: Record<string, unknown>
) {
const currentCount = currentState.votes.get(newValue) || 0;
// Create a new Map to ensure immutability
const newVotes = new Map(currentState.votes);
newVotes.set(newValue, currentCount + 1);
return { votes: newVotes };
currentState.votes.set(newValue, currentCount + 1);
return currentState;
}
resolve(
state: MajorityVoteState,
state: { votes: Map<PropertyTypes, number> },
_allStates?: Record<string, unknown>
): PropertyTypes | undefined {
let maxCount = 0;
let result: PropertyTypes | undefined;

43
src/views/resolvers/custom-resolvers/plugins/max.plugin.ts
View File

@ -1,48 +1,37 @@
import { PropertyID, PropertyTypes } from "@src/core/types";
import { CollapsedDelta } from "@src/views/lossless";
import { ResolverPlugin, DependencyStates } from "../plugin";
type MaxPluginState = {
max?: number;
};
import { PropertyTypes } from "../../../../core/types";
import { CollapsedDelta } from "../../../lossless";
import { ResolverPlugin } from "../plugin";
/**
* Numeric max plugin
*
* Tracks the maximum numeric value
*/
export class MaxPlugin<Target extends PropertyID> implements ResolverPlugin<MaxPluginState, Target> {
export class MaxPlugin implements ResolverPlugin<{ max?: number }> {
name = 'max';
readonly dependencies: Target[] = [];
dependencies: string[] = [];
constructor(private readonly target?: Target) {
if (target) {
this.dependencies = [target];
}
}
initialize(dependencies: DependencyStates): MaxPluginState {
return { max: this.target ? dependencies[this.target] as number : undefined };
initialize() {
return { max: undefined };
}
update(
currentState: MaxPluginState,
newValue?: PropertyTypes,
_delta?: CollapsedDelta,
dependencies?: DependencyStates
): MaxPluginState {
// const numValue = typeof newValue === 'number' ? newValue : parseFloat(String(newValue));
const numValue = (this.target ? dependencies?.[this.target] : newValue) as number;
currentState: { max?: number },
newValue: PropertyTypes,
_delta: CollapsedDelta,
_allStates?: Record<string, unknown>
) {
const numValue = typeof newValue === 'number' ? newValue : parseFloat(String(newValue));
if (currentState.max === undefined || numValue > currentState.max) {
if (!isNaN(numValue) && (currentState.max === undefined || numValue > currentState.max)) {
return { max: numValue };
}
return currentState;
}
resolve(
state: MaxPluginState,
_dependencies?: DependencyStates
state: { max?: number },
_allStates?: Record<string, unknown>
): PropertyTypes | undefined {
return state.max;
}

39
src/views/resolvers/custom-resolvers/plugins/min.plugin.ts
View File

@ -1,46 +1,37 @@
import { PropertyTypes, PropertyID } from "../../../../core/types";
import { PropertyTypes } from "../../../../core/types";
import { CollapsedDelta } from "../../../lossless";
import { ResolverPlugin, DependencyStates } from "../plugin";
type MinPluginState = {
min?: number;
};
import { ResolverPlugin } from "../plugin";
/**
* Numeric min plugin
*
* Tracks the minimum numeric value
*/
export class MinPlugin<Target extends PropertyID> implements ResolverPlugin<MinPluginState, Target> {
export class MinPlugin implements ResolverPlugin<{ min?: number }> {
name = 'min';
readonly dependencies: Target[] = [];
dependencies: string[] = [];
constructor(private readonly target?: Target) {
if (target) {
this.dependencies = [target];
}
}
initialize(dependencies: DependencyStates): MinPluginState {
return { min: this.target ? dependencies[this.target] as number : undefined };
initialize() {
return { min: undefined };
}
update(
currentState: MinPluginState,
newValue?: PropertyTypes,
_delta?: CollapsedDelta,
dependencies?: DependencyStates
): MinPluginState {
const numValue = (this.target ? dependencies?.[this.target] : newValue) as number;
currentState: { min?: number },
newValue: PropertyTypes,
_delta: CollapsedDelta,
_allStates?: Record<string, unknown>
) {
const numValue = typeof newValue === 'number' ? newValue : parseFloat(String(newValue));
if (currentState.min === undefined || numValue < currentState.min) {
if (!isNaN(numValue) && (currentState.min === undefined || numValue < currentState.min)) {
return { min: numValue };
}
return currentState;
}
resolve(
state: MinPluginState,
state: { min?: number },
_allStates?: Record<string, unknown>
): PropertyTypes | undefined {
return state.min;
}

41
src/views/resolvers/custom-resolvers/plugins/running-average.plugin.ts
View File

@ -1,41 +0,0 @@
import { PropertyTypes } from "@src/core/types";
import { CollapsedDelta } from "@src/views/lossless";
import { ResolverPlugin, DependencyStates } from "../plugin";
type RunningAverageState = {
sum: number;
count: number;
};
/**
* Running Average Plugin
*
* Tracks the running average of numeric values
*/
export class RunningAveragePlugin implements ResolverPlugin<RunningAverageState, never> {
readonly dependencies = [] as const;
initialize(): RunningAverageState {
return { sum: 0, count: 0 };
}
update(
currentState: RunningAverageState,
newValue: PropertyTypes,
_delta: CollapsedDelta,
_dependencies: DependencyStates = {}
): RunningAverageState {
const numValue = typeof newValue === 'number' ? newValue : 0;
return {
sum: currentState.sum + numValue,
count: currentState.count + 1
};
}
resolve(
state: RunningAverageState,
_dependencies: DependencyStates = {}
): number {
return state.count > 0 ? state.sum / state.count : 0;
}
}

406
src/views/resolvers/custom-resolvers/resolver.ts
View File

@ -1,287 +1,231 @@
import { EntityProperties } from "../../../core/entity";
import { CollapsedDelta, Lossless, LosslessViewOne } from "../../lossless";
import { Lossy } from '../../lossy';
import { DomainEntityID, PropertyID, PropertyTypes } from "../../../core/types";
import { ResolverPlugin, DependencyStates } from "./plugin";
import { EntityRecord } from "@src/core/entity";
import Debug from 'debug';
import { DomainEntityID, PropertyID, PropertyTypes, ViewMany } from "../../../core/types";
import { ResolverPlugin } from "./plugin";
const debug = Debug('rz:resolver');
const debugState = Debug('rz:resolver:state');
/**
* The state of a property for a single entity
*/
type EntityState = Record<PropertyID, unknown>;
/**
* Entities with their plugin states
*/
type Accumulator = Record<DomainEntityID, EntityState>;
/**
* Entities with their resolved properties
*/
type Result = Record<DomainEntityID, EntityRecord>;
/**
* Type to map property IDs to their plugin types
*
* @template T - The type of the plugin's state
* @template D - The type of the plugin's dependencies (defaults to PropertyID)
*/
type PluginMap = {
[P in PropertyID]: ResolverPlugin<unknown, PropertyID>;
type PropertyState = {
plugin: ResolverPlugin;
state: unknown;
};
/**
* Resolver plugins are able to define (virtual) properties on entities.
* Plugins can depend on other plugins, which will be resolved in topological order
* each time the view is updated. (The view is updated when the hyperview ingests a delta
* pertaining to an entity.)
*/
export class CustomResolver extends Lossy<Accumulator, Result> {
readonly config: PluginMap;
readonly executionOrder: PropertyID[] = [];
readonly dependencyGraph: Map<PropertyID, Set<PropertyID>> = new Map();
type EntityState = {
[propertyId: PropertyID]: PropertyState;
};
/**
* Creates a new CustomResolver instance
* @param lossless - The Lossless instance to use for delta tracking
* @param config - A mapping of property IDs to their resolver plugins
type CustomResolverAccumulator = {
[entityId: DomainEntityID]: {
id: DomainEntityID;
properties: EntityState;
};
};
type CustomResolverResult = ViewMany<{
id: DomainEntityID;
properties: EntityProperties;
}>;
/**
* Extract value from delta for a specific property
*/
function extractValueFromDelta(propertyId: PropertyID, delta: CollapsedDelta): PropertyTypes | undefined {
for (const pointer of delta.pointers) {
for (const [key, value] of Object.entries(pointer)) {
if (key === propertyId && (typeof value === "string" || typeof value === "number")) {
return value;
}
}
}
return undefined;
}
export class CustomResolver extends Lossy<CustomResolverAccumulator, CustomResolverResult> {
private executionOrder: PropertyID[];
private readonly config: Record<PropertyID, ResolverPlugin>;
constructor(
lossless: Lossless,
config: PluginMap
config: Record<PropertyID, ResolverPlugin>
) {
super(lossless);
this.config = config;
this.buildDependencyGraph();
this.executionOrder = this.calculateExecutionOrder();
this.validateDependencies();
this.executionOrder = this.getExecutionOrder();
}
initializer(view: LosslessViewOne): CustomResolverAccumulator {
return {
[view.id]: { id: view.id, properties: {} }
};
}
/**
* If you know the key by which a plugin is registered, this will return the base name
* @param propertyId The key by which a plugin is registered
* @returns The base name of the plugin
* Validates that there are no circular dependencies between plugins
* @throws Error if circular dependencies are detected
*/
pluginBasenameFromKey(propertyId: PropertyID): PropertyID {
return this.config[propertyId]?.name || propertyId;
private validateDependencies(): void {
const visited = new Set<PropertyID>();
const visiting = new Set<PropertyID>();
const plugins = Object.entries(this.config);
const visit = (pluginId: PropertyID): void => {
if (visiting.has(pluginId)) {
throw new Error(`Circular dependency detected involving property: ${pluginId}`);
}
if (visited.has(pluginId)) {
return;
}
visiting.add(pluginId);
const plugin = this.config[pluginId];
// Visit all dependencies first
for (const dep of plugin?.dependencies || []) {
if (this.config[dep]) {
visit(dep);
} else {
throw new Error(`Plugin '${pluginId}' depends on unknown property: ${dep}`);
}
}
visiting.delete(pluginId);
visited.add(pluginId);
};
// Check each plugin for circular dependencies
for (const [id] of plugins) {
if (!visited.has(id)) {
visit(id);
}
}
}
/**
* If you know the base name of a plugin, this will return the key by which it is registered
* @param alias The alias of the plugin
* @returns The key by which it is registered
* Gets the execution order of properties based on their dependencies
* @returns Array of property IDs in execution order
*/
pluginKeyFromBasename(alias: PropertyID): PropertyID {
const entry = Object.entries(this.config).find(([_, plugin]) => plugin.name === alias);
if (!entry) return alias;
return entry[0];
}
/**
* Build the dependency graph for all plugins.
* We'll use the basenames of the plugins in the graph.
*/
private buildDependencyGraph(): void {
// Initialize the graph with all plugins
Object.keys(this.config).forEach(propertyId => {
const pluginId = this.pluginBasenameFromKey(propertyId);
this.dependencyGraph.set(pluginId, new Set());
});
// Add edges based on dependencies
Object.entries(this.config).forEach(([propertyId, plugin]) => {
const pluginId = this.pluginBasenameFromKey(propertyId);
const deps = plugin.dependencies || [];
deps.forEach((depId: string) => {
// This dependency may have an alias in our current config
const depKey = this.pluginKeyFromBasename(depId);
if (!this.config[depKey]) {
debug(`Config: ${JSON.stringify(this.config)}`)
throw new Error(`Dependency ${depId} not found for plugin ${propertyId}`);
}
this.dependencyGraph.get(depId)?.add(pluginId);
});
});
debug(`Config: ${JSON.stringify(this.config)}`);
debug(`Dependency graph: ${JSON.stringify(this.dependencyGraph)}`);
}
/**
* Calculate the execution order of properties based on their dependencies
* using Kahn's algorithm for topological sorting
*/
private calculateExecutionOrder(): PropertyID[] {
private getExecutionOrder(): PropertyID[] {
const visited = new Set<PropertyID>();
const order: PropertyID[] = [];
const inDegree = new Map<PropertyID, number>();
// Initialize in-degree count for all nodes
this.dependencyGraph.forEach((_, node) => {
inDegree.set(node, 0);
});
const visit = (pluginId: PropertyID): void => {
if (visited.has(pluginId)) return;
// Calculate in-degree for each node
this.dependencyGraph.forEach((deps) => {
deps.forEach(dep => {
inDegree.set(dep, (inDegree.get(dep) || 0) + 1);
});
});
const plugin = this.config[pluginId];
if (!plugin) return;
// Queue for nodes with no incoming edges
const queue: PropertyID[] = [];
inDegree.forEach((degree, node) => {
if (degree === 0) {
queue.push(node);
}
});
// Process nodes in topological order
while (queue.length > 0) {
const node = queue.shift()!;
order.push(node);
// Decrease in-degree for all neighbors
this.dependencyGraph.get(node)?.forEach(neighbor => {
const newDegree = (inDegree.get(neighbor) || 0) - 1;
inDegree.set(neighbor, newDegree);
// If in-degree becomes zero, add to queue
if (newDegree === 0) {
queue.push(neighbor);
}
});
// Visit dependencies first
for (const dep of plugin.dependencies || []) {
visit(dep);
}
// Check for cycles
if (order.length !== this.dependencyGraph.size) {
throw new Error('Circular dependency detected in plugin dependencies');
// Then add this plugin
if (!visited.has(pluginId)) {
visited.add(pluginId);
order.push(pluginId);
}
};
// Visit each plugin
for (const id of Object.keys(this.config)) {
visit(id);
}
return order;
}
/**
* Get the resolved states of all dependencies for a plugin
* @param entityState The state of the entity
* @param dependencies The dependencies to resolve
*
*/
private getDependencyStates(
entityState: EntityState,
plugin: ResolverPlugin<unknown, string>
): DependencyStates {
const dependencyStates = {} as DependencyStates;
for (const depId of plugin.dependencies || []) {
const depKey = this.pluginKeyFromBasename(depId);
const depPlugin = this.config[depKey];
const depValue = entityState[depKey];
if (depValue) {
// Resolve the dependency's dependencies first
const depDependencies = this.getDependencyStates(
entityState,
depPlugin
);
// Resolve the dependency's state
dependencyStates[depId] = depPlugin.resolve(
depValue,
depDependencies
);
}
public reducer(
acc: CustomResolverAccumulator,
cur: LosslessViewOne
): CustomResolverAccumulator {
if (!acc[cur.id]) {
acc[cur.id] = { id: cur.id, properties: {} };
}
return dependencyStates;
// Get the execution order based on dependencies
const executionOrder = this.getExecutionOrder();
// First pass: collect all current states for this entity
const allStates: Record<PropertyID, unknown> = {};
for (const [propertyId, propertyState] of Object.entries(acc[cur.id].properties)) {
allStates[propertyId] = propertyState.state;
}
/**
* Update the state with new deltas from the view
*/
reducer(acc: Accumulator, {id: entityId, propertyDeltas}: LosslessViewOne): Accumulator {
debug(`Processing deltas for entity: ${entityId}`);
debug('Property deltas:', JSON.stringify(propertyDeltas, null, 2));
// Process each property in dependency order
for (const propertyId of executionOrder) {
const deltas = cur.propertyDeltas[propertyId];
if (!deltas) continue;
if (!acc[entityId]) {
acc[entityId] = {};
const plugin = this.config[propertyId];
if (!plugin) continue;
// Initialize property state if it doesn't exist
if (!acc[cur.id].properties[propertyId]) {
acc[cur.id].properties[propertyId] = {
plugin,
state: plugin.initialize()
};
allStates[propertyId] = acc[cur.id].properties[propertyId].state;
}
const entityState = acc[entityId];
// Now let's go through each plugin in order.
for (const pluginId of this.executionOrder) {
const pluginKey = this.pluginKeyFromBasename(pluginId);
const plugin = this.config[pluginKey];
if (!plugin) throw new Error(`Plugin for property ${pluginId} not found`);
debug(`Processing plugin: ${pluginId} (key: ${pluginKey})`);
// We need to resolve dependencies, including entity properties that are not plugins.
const dependencies = this.getDependencyStates(entityState, plugin);
// Initialize the plugin if it hasn't been initialized yet
const pluginState = entityState[pluginKey] ?? plugin.initialize(dependencies);
const deltaPropertyValues : Record<PropertyID, PropertyTypes> = {};
let propertyValue : PropertyTypes | undefined;
let updateDelta : CollapsedDelta | undefined;
for (const [propertyId, deltas] of Object.entries(propertyDeltas)) {
// Process each delta for this property
const propertyState = acc[cur.id].properties[propertyId];
for (const delta of deltas) {
// Iterate through the pointers; throw an error if a duplicate key is found
for (const pointer of delta.pointers) {
if (deltaPropertyValues[propertyId]) {
// It's possible that there are multiple deltas in this set with the same property ID.
// That can only happen if they are part of a transaction. Otherwise this function is
// only called once per delta, per entity affected.
throw new Error(`Duplicate property ID ${propertyId} found in delta ${delta.id}`);
}
deltaPropertyValues[propertyId] = pointer[propertyId];
// If there's an updated entity property matching the plugin key,
// pass it to the plugin update as the new property value.
if (propertyId === pluginKey) {
propertyValue = pointer[propertyId];
updateDelta = delta;
}
const value = extractValueFromDelta(propertyId, delta);
if (value !== undefined) {
propertyState.state = propertyState.plugin.update(
propertyState.state,
value,
delta,
allStates
);
// Update the state in our tracking object
allStates[propertyId] = propertyState.state;
}
}
}
// Update the plugin state with the new delta
entityState[pluginKey] = plugin.update(pluginState, propertyValue, updateDelta, dependencies);
debugState(`Updated entity state for ${entityId}:`, JSON.stringify(entityState[pluginKey], null, 2));
// Handle any properties not in the execution order (shouldn't normally happen)
for (const [propertyId, _deltas] of Object.entries(cur.propertyDeltas)) {
if (!executionOrder.includes(propertyId) && this.config[propertyId]) {
console.warn(`Property '${propertyId}' not in execution order but has deltas`);
}
}
return acc;
}
resolver(acc: Accumulator, entityIds: DomainEntityID[]) {
const result: Result = {};
debug('Initial accumulator state:', JSON.stringify(acc, null, 2));
resolver(cur: CustomResolverAccumulator): CustomResolverResult {
const res: CustomResolverResult = {};
for (const entityId in acc) {
if (!entityIds.includes(entityId)) continue;
result[entityId] = {
id: entityId,
properties: {}
};
for (const [entityId, entity] of Object.entries(cur)) {
const entityResult: { id: string; properties: EntityProperties } = { id: entityId, properties: {} };
for (const propertyId of this.executionOrder) {
const pluginKey = this.pluginKeyFromBasename(propertyId);
const plugin = this.config[pluginKey];
if (!plugin) throw new Error(`Plugin for property ${propertyId} not found`);
// First pass: collect all states for this entity
const allStates: Record<PropertyID, unknown> = {};
for (const [propertyId, propertyState] of Object.entries(entity.properties)) {
allStates[propertyId] = propertyState.state;
}
debug(`Processing property: ${propertyId} (key: ${pluginKey})`);
const dependencies = this.getDependencyStates(acc[entityId], plugin);
debug(`Dependencies for ${propertyId}:`, JSON.stringify(dependencies, null, 2));
const state = acc[entityId][pluginKey] || plugin.initialize(dependencies);
debug(`State for ${propertyId}:`, JSON.stringify(state, null, 2));
const resolvedValue = plugin.resolve(state, dependencies);
if (resolvedValue === undefined) throw new Error(`Resolved value for property ${propertyId} is undefined`)
debug(`Resolved value for ${propertyId}:`, resolvedValue);
result[entityId].properties[pluginKey] = resolvedValue;
// Second pass: resolve each property with access to all states
for (const [propertyId, propertyState] of Object.entries(entity.properties)) {
const resolvedValue = propertyState.plugin.resolve(
propertyState.state,
allStates
);
// Only add the property if the resolved value is not undefined
if (resolvedValue !== undefined) {
entityResult.properties[propertyId] = resolvedValue;
}
}
return result;
// Only include entities that have at least one resolved property
if (Object.keys(entityResult.properties).length > 0) {
res[entityId] = entityResult;
}
}
return res;
}
}

8
src/views/resolvers/timestamp-resolvers.ts
View File

@ -4,11 +4,13 @@ import { Lossy } from '../lossy';
import { DomainEntityID, PropertyID, PropertyTypes, Timestamp, ViewMany } from "../../core/types";
import { valueFromCollapsedDelta } from "./aggregation-resolvers";
// Moved here from last-write-wins.ts before removing that file
export type TimestampedProperty = {
value: PropertyTypes,
timeUpdated: Timestamp
};
// Moved here from last-write-wins.ts before removing that file
export type TimestampedProperties = {
[key: PropertyID]: TimestampedProperty
};
@ -81,6 +83,12 @@ export class TimestampResolver extends Lossy<Accumulator, Result> {
super(lossless);
}
initializer(view: LosslessViewOne): Accumulator {
return {
[view.id]: { id: view.id, properties: {} }
};
}
reducer(acc: Accumulator, cur: LosslessViewOne): Accumulator {
if (!acc[cur.id]) {
acc[cur.id] = { id: cur.id, properties: {} };

6
tsconfig.json
View File

@ -16,12 +16,6 @@
"typeRoots": [
"./node_modules/@types"
],
"paths": {
"@src": ["./src"],
"@src/*": ["./src/*"],
"@test-helpers": ["__tests__/__helpers__"],
"@test-helpers/*": ["__tests__/__helpers__/*"]
},
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": false