@hops-ops/distributed 0.0.0

package/dist/replica/identity/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const GRAPHQL_NAME: RegExp;
+export declare const MAX_VARIABLE_CODEC_DEPTH = 64;
+export declare const FILTER_OPERATORS: Set<string>;

package/dist/replica/identity/constants.js

@@ -0,0 +1,18 @@
+export const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
+export const MAX_VARIABLE_CODEC_DEPTH = 64;
+export const FILTER_OPERATORS = new Set([
+    '_eq',
+    '_neq',
+    '_gt',
+    '_gte',
+    '_lt',
+    '_lte',
+    '_in',
+    '_nin',
+    '_is_null',
+    '_like',
+    '_ilike',
+    '_contains',
+    '_contained_in',
+    '_has_key'
+]);

package/dist/replica/identity/implementation.d.ts

@@ -0,0 +1,5 @@
+/** Re-export surface for identity implementation modules (body-split). */
+export * from './constants.js';
+export * from './keys.js';
+export * from './codec.js';
+export * from './clone.js';

package/dist/replica/identity/implementation.js

@@ -0,0 +1,5 @@
+/** Re-export surface for identity implementation modules (body-split). */
+export * from './constants.js';
+export * from './keys.js';
+export * from './codec.js';
+export * from './clone.js';

package/dist/replica/identity/index.d.ts

@@ -0,0 +1,3 @@
+export { replicaRecordKey, replicaIndexKey, resolveArguments, resolveReplicaArgumentValue, coverageFromArtifact } from './keys.js';
+export { canonicalizeOperationVariables } from './codec.js';
+export { canonicalVariables, cloneJsonObject, cloneJsonValue, canonicalCacheValue } from './clone.js';

package/dist/replica/identity/index.js

@@ -0,0 +1,3 @@
+export { replicaRecordKey, replicaIndexKey, resolveArguments, resolveReplicaArgumentValue, coverageFromArtifact } from './keys.js';
+export { canonicalizeOperationVariables } from './codec.js';
+export { canonicalVariables, cloneJsonObject, cloneJsonValue, canonicalCacheValue } from './clone.js';

package/dist/replica/identity/keys.d.ts

@@ -0,0 +1,29 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaArgumentValue, ReplicaArgumentsArtifact, ReplicaCoverageArtifact, ReplicaIdentity, ReplicaIndexCoverage, ReplicaModelArtifact, ReplicaValue } from '../types.js';
+export declare function replicaRecordKey(model: ReplicaModelArtifact, identity: ReplicaIdentity): string;
+export declare function replicaIndexKey(input: {
+    readonly parent?: string;
+    readonly field: string;
+    readonly arguments?: Readonly<Record<string, ReplicaValue>>;
+}): string;
+export declare function resolveArguments(artifact: ReplicaArgumentsArtifact | undefined, variables: GraphqlVariables, coverage?: ReplicaCoverageArtifact): Readonly<Record<string, ReplicaValue>>;
+export declare function resolveReplicaArgumentValue(source: ReplicaArgumentValue, variables: GraphqlVariables, position?: 'argument' | 'object' | 'list'): ReplicaValue | undefined;
+export declare function coverageFromArtifact(artifact: ReplicaCoverageArtifact | undefined, argumentsValue: Readonly<Record<string, ReplicaValue>>, returned: number): ReplicaIndexCoverage;
+export type OffsetCoverageArtifact = Extract<ReplicaCoverageArtifact, {
+    readonly kind: 'offset';
+}>;
+export declare function effectiveOffsetArguments(argumentsValue: Readonly<Record<string, ReplicaValue>>, artifact: OffsetCoverageArtifact): Readonly<Record<string, ReplicaValue>>;
+export declare function effectiveOffsetWindow(argumentsValue: Readonly<Record<string, ReplicaValue>>, artifact: OffsetCoverageArtifact): {
+    readonly offset: number;
+    readonly limit?: number;
+};
+/**
+ * Distributed's SQL compiler treats an omitted, explicit-null, or negative
+ * nullable Int as absent before applying the server default. Other values
+ * cannot appear in a successful GraphQL response and remain fail-fast here.
+ */
+export declare function serverNonNegativeIntegerArgument(argumentsValue: Readonly<Record<string, ReplicaValue>>, argument: string | undefined): number | undefined;
+export declare function coverageBound(value: number | undefined, field: string): number | undefined;
+export declare function cacheArgument<K extends 'after' | 'before'>(argumentsValue: Readonly<Record<string, ReplicaValue>>, argument: string | undefined, key: K): Partial<Record<K, ReplicaValue>>;
+export declare function numericCoverageArgument<K extends 'first' | 'last'>(argumentsValue: Readonly<Record<string, ReplicaValue>>, argument: string | undefined, key: K): Partial<Record<K, number>>;
+export declare function numericArgument(argumentsValue: Readonly<Record<string, ReplicaValue>>, argument: string | undefined): number | undefined;

package/dist/replica/identity/keys.js

@@ -0,0 +1,173 @@
+import { cacheIndexKey } from '../../internal/cache-engine.js';
+import { assertName } from '../../lib/assert-name.js';
+import { freezeRecord } from '../../lib/freeze-record.js';
+import { canonicalCacheValue, cloneJsonValue } from './clone.js';
+export function replicaRecordKey(model, identity) {
+    assertName(model.id, 'model id');
+    if (!Array.isArray(model.identityFields) || model.identityFields.length === 0) {
+        throw new TypeError(`model ${model.id} must declare at least one identity field`);
+    }
+    const parts = Array.isArray(identity) ? identity : [identity];
+    if (parts.length !== model.identityFields.length) {
+        throw new TypeError(`model ${model.id} identity expected ${model.identityFields.length} part(s), received ${parts.length}`);
+    }
+    return `record:${encodeURIComponent(model.id)}:${canonicalCacheValue(parts.map((part) => cloneJsonValue(part)))}`;
+}
+export function replicaIndexKey(input) {
+    return cacheIndexKey({
+        ...(input.parent === undefined ? {} : { parent: input.parent }),
+        field: input.field,
+        arguments: input.arguments ?? {}
+    });
+}
+export function resolveArguments(artifact, variables, coverage) {
+    const entries = [];
+    for (const [argument, source] of Object.entries(artifact ?? {})) {
+        assertName(argument, 'GraphQL argument');
+        const value = resolveReplicaArgumentValue(source, variables);
+        if (value !== undefined)
+            entries.push([argument, value]);
+    }
+    const resolved = freezeRecord(entries);
+    return coverage?.kind === 'offset'
+        ? effectiveOffsetArguments(resolved, coverage)
+        : resolved;
+}
+export function resolveReplicaArgumentValue(source, variables, position = 'argument') {
+    if (source.kind === 'literal')
+        return cloneJsonValue(source.value);
+    if (source.kind === 'variable') {
+        assertName(source.name, 'GraphQL variable');
+        if (!Object.prototype.hasOwnProperty.call(variables, source.name) ||
+            variables[source.name] === undefined) {
+            return position === 'list' ? null : undefined;
+        }
+        return cloneJsonValue(variables[source.name]);
+    }
+    if (source.kind === 'list') {
+        if (!Array.isArray(source.items)) {
+            throw new TypeError('GraphQL list argument source must contain an items array');
+        }
+        return Object.freeze(source.items.map((item) => resolveReplicaArgumentValue(item, variables, 'list') ?? null));
+    }
+    if (source.kind === 'object') {
+        if (source.fields === null ||
+            typeof source.fields !== 'object' ||
+            Array.isArray(source.fields)) {
+            throw new TypeError('GraphQL object argument source must contain a fields object');
+        }
+        const entries = [];
+        for (const [field, value] of Object.entries(source.fields)) {
+            assertName(field, 'GraphQL input field');
+            const resolved = resolveReplicaArgumentValue(value, variables, 'object');
+            if (resolved !== undefined)
+                entries.push([field, resolved]);
+        }
+        return freezeRecord(entries);
+    }
+    throw new TypeError('unsupported argument source');
+}
+export function coverageFromArtifact(artifact, argumentsValue, returned) {
+    if (artifact === undefined || artifact.kind === 'complete') {
+        return Object.freeze({ kind: 'complete' });
+    }
+    if (artifact.kind === 'offset') {
+        const window = effectiveOffsetWindow(argumentsValue, artifact);
+        return Object.freeze({
+            kind: 'offset',
+            offset: window.offset,
+            ...(window.limit === undefined ? {} : { limit: window.limit }),
+            returned
+        });
+    }
+    return Object.freeze({
+        kind: 'cursor',
+        ...cacheArgument(argumentsValue, artifact.afterArgument, 'after'),
+        ...cacheArgument(argumentsValue, artifact.beforeArgument, 'before'),
+        ...numericCoverageArgument(argumentsValue, artifact.firstArgument, 'first'),
+        ...numericCoverageArgument(argumentsValue, artifact.lastArgument, 'last')
+    });
+}
+export function effectiveOffsetArguments(argumentsValue, artifact) {
+    const window = effectiveOffsetWindow(argumentsValue, artifact);
+    const entries = new Map(Object.entries(argumentsValue));
+    if (artifact.offsetArgument !== undefined) {
+        assertName(artifact.offsetArgument, 'offset pagination argument');
+        entries.set(artifact.offsetArgument, window.offset);
+    }
+    if (artifact.limitArgument !== undefined) {
+        assertName(artifact.limitArgument, 'limit pagination argument');
+        if (window.limit === undefined)
+            entries.delete(artifact.limitArgument);
+        else
+            entries.set(artifact.limitArgument, window.limit);
+    }
+    return freezeRecord([...entries.entries()]);
+}
+export function effectiveOffsetWindow(argumentsValue, artifact) {
+    const configuredDefault = coverageBound(artifact.defaultLimit, 'defaultLimit');
+    const configuredMax = coverageBound(artifact.maxLimit, 'maxLimit');
+    if (configuredDefault !== undefined &&
+        configuredMax !== undefined &&
+        configuredDefault > configuredMax) {
+        throw new TypeError('offset coverage defaultLimit must not exceed maxLimit');
+    }
+    const offset = serverNonNegativeIntegerArgument(argumentsValue, artifact.offsetArgument) ?? 0;
+    const requested = serverNonNegativeIntegerArgument(argumentsValue, artifact.limitArgument);
+    const selected = requested ?? configuredDefault;
+    const limit = selected === undefined || configuredMax === undefined
+        ? selected
+        : Math.min(selected, configuredMax);
+    return {
+        offset,
+        ...(limit === undefined ? {} : { limit })
+    };
+}
+/**
+ * Distributed's SQL compiler treats an omitted, explicit-null, or negative
+ * nullable Int as absent before applying the server default. Other values
+ * cannot appear in a successful GraphQL response and remain fail-fast here.
+ */
+export function serverNonNegativeIntegerArgument(argumentsValue, argument) {
+    if (argument === undefined ||
+        !Object.prototype.hasOwnProperty.call(argumentsValue, argument)) {
+        return undefined;
+    }
+    const value = argumentsValue[argument];
+    if (value === null)
+        return undefined;
+    if (!Number.isSafeInteger(value)) {
+        throw new TypeError(`pagination argument ${argument} must be an integer or null`);
+    }
+    if (value < 0)
+        return undefined;
+    return value === 0 ? 0 : value;
+}
+export function coverageBound(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`offset coverage ${field} must be a non-negative safe integer`);
+    }
+    return value;
+}
+export function cacheArgument(argumentsValue, argument, key) {
+    if (argument === undefined || !Object.prototype.hasOwnProperty.call(argumentsValue, argument)) {
+        return {};
+    }
+    return { [key]: argumentsValue[argument] };
+}
+export function numericCoverageArgument(argumentsValue, argument, key) {
+    const value = numericArgument(argumentsValue, argument);
+    return value === undefined ? {} : { [key]: value };
+}
+export function numericArgument(argumentsValue, argument) {
+    if (argument === undefined || !Object.prototype.hasOwnProperty.call(argumentsValue, argument)) {
+        return undefined;
+    }
+    const value = argumentsValue[argument];
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`pagination argument ${argument} must be a non-negative integer`);
+    }
+    return value;
+}

package/dist/replica/identity.d.ts

@@ -0,0 +1,2 @@
+/** Replica identity/keys and variable codec; implementation in ./identity/. */
+export { canonicalCacheValue, canonicalVariables, canonicalizeOperationVariables, cloneJsonObject, cloneJsonValue, coverageFromArtifact, replicaIndexKey, replicaRecordKey, resolveArguments, resolveReplicaArgumentValue } from './identity/index.js';

package/dist/replica/identity.js

@@ -0,0 +1,2 @@
+/** Replica identity/keys and variable codec; implementation in ./identity/. */
+export { canonicalCacheValue, canonicalVariables, canonicalizeOperationVariables, cloneJsonObject, cloneJsonValue, coverageFromArtifact, replicaIndexKey, replicaRecordKey, resolveArguments, resolveReplicaArgumentValue } from './identity/index.js';

package/dist/replica/index-maintenance/engine.d.ts

@@ -0,0 +1,84 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaFilterArtifact, ReplicaCoverageArtifact, ReplicaIndexRecordChange, ReplicaIndexRelationshipChange, ReplicaIndexSemanticChange, ReplicaObjectBranch, ReplicaOperationArtifact, ReplicaOrderArtifact, ReplicaPaginationArtifact, ReplicaRelationshipArtifact, ReplicaRootSelection, ReplicaSurfaceTrustedPresetDescriptor, ReplicaValue } from '../types.js';
+import type { ReplicaIndexMaintenanceDecision, ReplicaIndexMaintenanceIndex, ReplicaIndexMaintenanceReason, ReplicaIndexMaintenanceReasonCode, ReplicaIndexMaintenanceRecord, ReplicaIndexSemanticLayer } from './types.js';
+export type PlanKind = 'entity' | 'relationship' | 'snapshot';
+export type RegisteredPlan = {
+    readonly registration: string;
+    readonly kind: PlanKind;
+    readonly exactIndexKey?: string;
+    readonly parentModel?: string;
+    readonly targetModel?: string;
+    readonly field: string;
+    readonly arguments: Readonly<Record<string, ReplicaValue>>;
+    readonly dependencies: readonly string[];
+    readonly cardinality: 'one' | 'many';
+    readonly filter?: ReplicaFilterArtifact;
+    readonly order?: ReplicaOrderArtifact;
+    readonly pagination?: ReplicaPaginationArtifact;
+    readonly coverage?: ReplicaCoverageArtifact;
+    readonly relationship?: ReplicaRelationshipArtifact;
+    readonly variables: GraphqlVariables;
+    readonly trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[];
+    readonly path: readonly (string | number)[];
+    readonly signature: string;
+};
+export type MutableRecord = {
+    readonly key: string;
+    readonly model: string;
+    fields: Record<string, ReplicaValue>;
+};
+export type AppliedChanges = {
+    readonly baseRecords: ReadonlyMap<string, MutableRecord>;
+    readonly records: Map<string, MutableRecord>;
+    readonly recordChanges: readonly ReplicaIndexRecordChange[];
+    readonly relationshipChanges: readonly ReplicaIndexRelationshipChange[];
+    readonly invalidatedDependencies: ReadonlySet<string>;
+    readonly allDependencies: ReadonlySet<string>;
+};
+export declare function formatReplicaIndexStaleReason(reasonValue: ReplicaIndexMaintenanceReason): string;
+export declare function compilePlans(registration: string, artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>, variables: GraphqlVariables): readonly RegisteredPlan[];
+export declare function compileSelectionPlans(output: RegisteredPlan[], registration: string, selection: ReplicaRootSelection['selection'], parentModel: string | undefined, variables: GraphqlVariables, trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[], path: readonly (string | number)[]): void;
+export declare function compileBranchPlan(output: RegisteredPlan[], registration: string, branch: ReplicaObjectBranch, parentModel: string | undefined, variables: GraphqlVariables, trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[], path: readonly (string | number)[]): void;
+export declare function plan(value: Omit<RegisteredPlan, 'signature'>): RegisteredPlan;
+export declare function selectionModel(selection: ReplicaRootSelection['selection']): string | undefined;
+export declare function instantiatePlans(plans: readonly RegisteredPlan[], indexes: ReadonlyMap<string, ReplicaIndexMaintenanceIndex>): Map<string, RegisteredPlan[]>;
+export declare function appendPlan(output: Map<string, RegisteredPlan[]>, key: string, value: RegisteredPlan): void;
+export declare function applyLayers(base: readonly ReplicaIndexMaintenanceRecord[], layers: readonly ReplicaIndexSemanticLayer[]): AppliedChanges;
+export declare function validateIndexes(input: readonly ReplicaIndexMaintenanceIndex[]): Map<string, ReplicaIndexMaintenanceIndex>;
+export declare function planAffected(planValue: RegisteredPlan, index: ReplicaIndexMaintenanceIndex, changes: AppliedChanges): boolean;
+export declare function evaluatePlan(planValue: RegisteredPlan, index: ReplicaIndexMaintenanceIndex, changes: AppliedChanges, trustedPresets: readonly DistributedTrustedPreset[]): ReplicaIndexMaintenanceDecision;
+export declare function maintainEntityIndex(planValue: RegisteredPlan, index: ReplicaIndexMaintenanceIndex, changes: AppliedChanges, trustedPresets: readonly DistributedTrustedPreset[]): ReplicaIndexMaintenanceDecision;
+export declare function certifyOffsetCoverage(planValue: RegisteredPlan, index: ReplicaIndexMaintenanceIndex, confirmedRecords: number, changeKind: 'insert' | 'delete' | 'reorder' | 'stable_update'): ReplicaIndexMaintenanceReason | undefined;
+export declare function parentRecordChangeAffectsRelationship(planValue: RegisteredPlan, index: ReplicaIndexMaintenanceIndex, change: ReplicaIndexRecordChange): boolean;
+export declare function relationshipMembership(planValue: RegisteredPlan, index: ReplicaIndexMaintenanceIndex, target: MutableRecord | undefined, records: ReadonlyMap<string, MutableRecord>): {
+    readonly related: boolean;
+} | {
+    readonly reason: ReplicaIndexMaintenanceReason;
+};
+export declare function evaluateMembership(planValue: RegisteredPlan, record: MutableRecord, trustedPresets: readonly DistributedTrustedPreset[]): {
+    readonly matches: boolean;
+} | {
+    readonly reason: ReplicaIndexMaintenanceReason;
+};
+export declare function sortRecords(keys: readonly string[], order: ReplicaOrderArtifact, records: ReadonlyMap<string, MutableRecord>, variables: GraphqlVariables, path: readonly (string | number)[]): {
+    readonly records: readonly string[];
+} | {
+    readonly reason: ReplicaIndexMaintenanceReason;
+};
+export declare function relationshipChangeMatches(planValue: RegisteredPlan, index: ReplicaIndexMaintenanceIndex, change: ReplicaIndexRelationshipChange): boolean;
+export declare function isRelationshipChange(change: ReplicaIndexSemanticChange): change is ReplicaIndexRelationshipChange;
+export declare function validateDependencies(value: readonly string[]): readonly string[];
+export declare function intersects(left: readonly string[], right: ReadonlySet<string>): boolean;
+export declare function recordKeyMatchesModel(key: string, model: string): boolean;
+export declare function firstDuplicate(values: readonly string[]): string | undefined;
+export declare function write(indexKey: string, records: readonly string[]): ReplicaIndexMaintenanceDecision;
+export declare function stale(indexKey: string, reasonValue: ReplicaIndexMaintenanceReason): ReplicaIndexMaintenanceDecision;
+export declare function unchanged(indexKey: string): ReplicaIndexMaintenanceDecision;
+export declare function reason(code: ReplicaIndexMaintenanceReasonCode, path: readonly (string | number)[], message: string): ReplicaIndexMaintenanceReason;
+export declare function sameStringList(left: readonly string[], right: readonly string[]): boolean;
+export declare function sameValue(left: unknown, right: unknown): boolean;
+export declare function cloneRecord(value: Readonly<Record<string, ReplicaValue>>): Readonly<Record<string, ReplicaValue>>;
+export declare function cloneValue(value: ReplicaValue): ReplicaValue;
+export declare function canonicalValue(value: unknown): string;
+export declare function validateName(value: string, description: string): void;