@hops-ops/distributed 0.0.0

package/dist/replica/revalidation.js

@@ -0,0 +1,86 @@
+/**
+ * Compile one validated command inventory into a reusable operation matcher.
+ *
+ * Adapters only forward generated plans; the replica owns knowledge of active
+ * operation artifacts and therefore remains the framework-neutral coordinator.
+ */
+export function createReplicaRevalidationMatcher(plan) {
+    const inventory = revalidationInventory(plan);
+    return (artifact) => inventory.global ||
+        artifact.roots.some((root) => intersects(root.dependencies, inventory.dependencies) ||
+            selectionMatches(root.selection, undefined, inventory));
+}
+function selectionMatches(selection, parentModel, inventory) {
+    const model = selection.storage.kind === 'normalized'
+        ? selection.storage.model
+        : parentModel;
+    if (selection.storage.kind === 'normalized' &&
+        inventory.models.has(selection.storage.model)) {
+        return true;
+    }
+    for (const member of selection.members) {
+        if (member.kind !== 'branch')
+            continue;
+        if (intersects(member.dependencies, inventory.dependencies))
+            return true;
+        if (member.semantic === 'relationship' &&
+            model !== undefined &&
+            inventory.relationships.has(relationshipKey(model, member.field, member.relationship.targetModel))) {
+            return true;
+        }
+        if (selectionMatches(member.selection, model, inventory))
+            return true;
+    }
+    return false;
+}
+function revalidationInventory(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        !Array.isArray(value.dependencies) ||
+        !Array.isArray(value.models) ||
+        !Array.isArray(value.relationships)) {
+        invalidPlan();
+    }
+    const dependencies = stringSet(value.dependencies, 'dependencies');
+    const models = stringSet(value.models, 'models');
+    const relationships = new Set();
+    for (const [index, relationship] of value.relationships.entries()) {
+        if (relationship === null ||
+            typeof relationship !== 'object' ||
+            !validName(relationship.sourceModel) ||
+            !validName(relationship.field) ||
+            !validName(relationship.targetModel)) {
+            invalidPlan(`relationships[${index}]`);
+        }
+        relationships.add(relationshipKey(relationship.sourceModel, relationship.field, relationship.targetModel));
+    }
+    return Object.freeze({
+        dependencies,
+        models,
+        relationships,
+        global: dependencies.size === 0 &&
+            models.size === 0 &&
+            relationships.size === 0
+    });
+}
+function stringSet(values, path) {
+    const result = new Set();
+    for (const [index, value] of values.entries()) {
+        if (!validName(value))
+            invalidPlan(`${path}[${index}]`);
+        result.add(value);
+    }
+    return result;
+}
+function validName(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function intersects(left, right) {
+    return left.some((value) => right.has(value));
+}
+function relationshipKey(sourceModel, field, targetModel) {
+    return JSON.stringify([sourceModel, field, targetModel]);
+}
+function invalidPlan(path) {
+    throw new TypeError(`replica revalidation plan${path === undefined ? '' : ` ${path}`} is invalid`);
+}

package/dist/replica/selection.d.ts

@@ -0,0 +1,20 @@
+import type { ReplicaObjectBranch, ReplicaRootSelection, ReplicaScalarSelection, ReplicaSelectionStorage } from './types.js';
+export type RuntimeScalarSelection = ReplicaScalarSelection & {
+    readonly nullable: boolean;
+};
+export type RuntimeObjectSelection = {
+    readonly typename: string;
+    readonly storage: ReplicaSelectionStorage;
+    readonly members: readonly RuntimeObjectMember[];
+};
+export type RuntimeObjectBranch = Omit<ReplicaObjectBranch, 'selection'> & {
+    readonly selection: RuntimeObjectSelection;
+    readonly expose?: boolean;
+};
+export type RuntimeObjectMember = RuntimeScalarSelection | RuntimeObjectBranch;
+export type RuntimeRootSelection = Omit<ReplicaRootSelection, 'nullable' | 'selection'> & {
+    readonly nullable: boolean;
+    readonly selection: RuntimeObjectSelection;
+};
+export declare function runtimeRoot(selection: ReplicaRootSelection): RuntimeRootSelection;
+export declare function embeddedRecordKey(artifactId: string, enclosingIndexKey: string, ordinal: number | undefined): string;

package/dist/replica/selection.js

@@ -0,0 +1,109 @@
+import { assertName } from '../lib/assert-name.js';
+export function runtimeRoot(selection) {
+    assertBranchShape(selection, 'root');
+    if (typeof selection.nullable !== 'boolean') {
+        throw new TypeError(`root ${selection.responseKey} must declare exact nullability`);
+    }
+    return Object.freeze({
+        ...selection,
+        nullable: selection.nullable,
+        selection: runtimeObject(selection.selection)
+    });
+}
+export function embeddedRecordKey(artifactId, enclosingIndexKey, ordinal) {
+    const slot = ordinal === undefined ? 'one' : `ordinal:${ordinal}`;
+    return `embedded:${encodeURIComponent(artifactId)}:${encodeURIComponent(enclosingIndexKey)}:${slot}`;
+}
+function runtimeObject(selection) {
+    assertName(selection.typename, 'selection typename');
+    assertStorage(selection.storage);
+    if (!Array.isArray(selection.members)) {
+        throw new TypeError(`selection ${selection.typename} members must be an array`);
+    }
+    return Object.freeze({
+        typename: selection.typename,
+        storage: freezeStorage(selection.storage),
+        members: Object.freeze(selection.members.map((member) => {
+            if (member.kind === 'scalar')
+                return runtimeScalar(member);
+            if (member.kind !== 'branch') {
+                throw new TypeError(`selection ${selection.typename} contains an unsupported member`);
+            }
+            assertBranchShape(member, `branch ${member.responseKey}`);
+            if (member.semantic !== 'relationship' &&
+                member.semantic !== 'aggregate' &&
+                member.semantic !== 'aggregate_fields' &&
+                member.semantic !== 'aggregate_nodes') {
+                throw new TypeError(`branch ${member.responseKey} has unsupported semantic ${String(member.semantic)}`);
+            }
+            if (typeof member.nullable !== 'boolean') {
+                throw new TypeError(`branch ${member.responseKey} must declare exact nullability`);
+            }
+            return Object.freeze({
+                ...member,
+                dependencies: freezeDependencies(member.dependencies, member.responseKey),
+                selection: runtimeObject(member.selection)
+            });
+        }))
+    });
+}
+function runtimeScalar(selection) {
+    if (selection.kind !== 'scalar') {
+        throw new TypeError('object scalar member must have kind scalar');
+    }
+    assertName(selection.responseKey, 'scalar response key');
+    assertName(selection.field, `scalar ${selection.responseKey} field`);
+    assertName(selection.codec, `scalar ${selection.responseKey} codec`);
+    if (typeof selection.nullable !== 'boolean') {
+        throw new TypeError(`scalar ${selection.responseKey} must declare exact nullability`);
+    }
+    return Object.freeze({
+        ...selection,
+        nullable: selection.nullable
+    });
+}
+function assertBranchShape(selection, description) {
+    assertName(selection.responseKey, `${description} response key`);
+    assertName(selection.field, `${description} field`);
+    if (selection.cardinality !== 'one' && selection.cardinality !== 'many') {
+        throw new TypeError(`${description} has unsupported cardinality`);
+    }
+    freezeDependencies(selection.dependencies, selection.responseKey);
+}
+function freezeDependencies(dependencies, responseKey) {
+    if (!Array.isArray(dependencies)) {
+        throw new TypeError(`branch ${responseKey} dependencies must be an array`);
+    }
+    for (const dependency of dependencies) {
+        assertName(dependency, `branch ${responseKey} dependency`);
+    }
+    return Object.freeze([...dependencies]);
+}
+function assertStorage(storage) {
+    if (storage.kind === 'embedded')
+        return;
+    if (storage.kind !== 'normalized') {
+        throw new TypeError('selection has unsupported storage');
+    }
+    assertName(storage.model, 'normalized model');
+    if (!Array.isArray(storage.identityFields) || storage.identityFields.length === 0) {
+        throw new TypeError(`normalized model ${storage.model} must declare at least one identity field`);
+    }
+    const unique = new Set();
+    for (const field of storage.identityFields) {
+        assertName(field, `normalized model ${storage.model} identity field`);
+        if (unique.has(field)) {
+            throw new TypeError(`normalized model ${storage.model} contains duplicate identity field ${field}`);
+        }
+        unique.add(field);
+    }
+}
+function freezeStorage(storage) {
+    if (storage.kind === 'embedded')
+        return Object.freeze({ kind: 'embedded' });
+    return Object.freeze({
+        kind: 'normalized',
+        model: storage.model,
+        identityFields: Object.freeze([...storage.identityFields])
+    });
+}