@hops-ops/distributed 0.0.0

package/dist/react/query.js

@@ -0,0 +1,99 @@
+'use client';
+import { useDebugValue, useMemo, useSyncExternalStore } from 'react';
+import { canonicalizeOperationVariables } from '../replica/identity.js';
+import { useDistributedReplica } from './context.js';
+const EMPTY_VARIABLES = Object.freeze({});
+/**
+ * React's commit-safe bridge around one framework-neutral ReplicaWatch.
+ *
+ * Constructing a core watch starts transport work, so this wrapper creates it
+ * only from React's subscribe phase. Server renders use the side-effect-free
+ * replica read path and therefore leave no abandoned watch behind.
+ */
+class ReactReplicaExternalStore {
+    #replica;
+    #artifact;
+    #variables;
+    #options;
+    #watch;
+    #snapshot;
+    #subscriberCount = 0;
+    constructor(replica, artifact, variables, options) {
+        this.#replica = replica;
+        this.#artifact = artifact;
+        this.#variables = variables;
+        this.#options = options;
+    }
+    getSnapshot = () => {
+        if (this.#watch !== undefined) {
+            this.#snapshot = this.#watch.get();
+        }
+        this.#snapshot ??= this.#replica.read(this.#artifact, this.#variables);
+        return this.#snapshot;
+    };
+    getServerSnapshot = () => this.getSnapshot();
+    subscribe = (notify) => {
+        const watch = this.#watch ?? this.#createWatch();
+        this.#subscriberCount += 1;
+        let active = true;
+        const unsubscribe = watch.subscribe((snapshot) => {
+            this.#snapshot = snapshot;
+            notify();
+        });
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            unsubscribe();
+            this.#subscriberCount -= 1;
+            if (this.#subscriberCount === 0 && this.#watch === watch) {
+                watch.destroy();
+                this.#watch = undefined;
+            }
+        };
+    };
+    refresh = async () => {
+        const activeWatch = this.#watch;
+        if (activeWatch !== undefined) {
+            await activeWatch.refresh();
+            return;
+        }
+        // This path is primarily defensive for an event fired before subscription
+        // commit. The temporary watch is always retired.
+        const temporaryWatch = this.#replica.watch(this.#artifact, this.#variables, this.#options);
+        try {
+            await temporaryWatch.refresh();
+            this.#snapshot = temporaryWatch.get();
+        }
+        finally {
+            temporaryWatch.destroy();
+        }
+    };
+    #createWatch() {
+        const watch = this.#replica.watch(this.#artifact, this.#variables, this.#options);
+        this.#watch = watch;
+        this.#snapshot = watch.get();
+        return watch;
+    }
+}
+/**
+ * Bind a generated operation artifact to React without introducing a React
+ * cache. All reads, fetches, live updates, optimism, and authorization fences
+ * continue through the supplied DistributedReplica.
+ */
+export function useDistributedQuery(artifact, ...args) {
+    const replica = useDistributedReplica();
+    const suppliedVariables = (args[0] ?? EMPTY_VARIABLES);
+    const live = args[1]?.live === true;
+    // Core canonicalization is the only operation-input authority. The JSON text
+    // is merely a React memo identity for that already-canonical frozen value.
+    const canonicalVariables = canonicalizeOperationVariables(artifact, suppliedVariables);
+    const variableIdentity = JSON.stringify(canonicalVariables);
+    const store = useMemo(() => new ReactReplicaExternalStore(replica, artifact, canonicalVariables, Object.freeze({ live })), [replica, artifact, variableIdentity, live]);
+    const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+    useDebugValue(`${artifact.id}: ${snapshot.status}`);
+    return useMemo(() => Object.freeze({
+        ...snapshot,
+        refresh: store.refresh
+    }), [snapshot, store]);
+}

package/dist/replica/command-id.d.ts

@@ -0,0 +1,2 @@
+/** Create a browser/Node UUIDv7 command identity. */
+export declare function createReplicaCommandId(): string;

package/dist/replica/command-id.js

@@ -0,0 +1,19 @@
+/** Create a browser/Node UUIDv7 command identity. */
+export function createReplicaCommandId() {
+    const crypto = globalThis.crypto;
+    if (!crypto || typeof crypto.getRandomValues !== 'function') {
+        throw new Error('replica commands require crypto.getRandomValues');
+    }
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    let timestamp = Date.now();
+    for (let index = 5; index >= 0; index -= 1) {
+        bytes[index] = timestamp & 0xff;
+        timestamp = Math.floor(timestamp / 256);
+    }
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = [...bytes].map((value) => value.toString(16).padStart(2, '0'));
+    return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex
+        .slice(6, 8)
+        .join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10).join('')}`;
+}

package/dist/replica/command-runtime/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const MAX_TRANSPORT_RETRIES = 8;
+export declare const MAX_OUTPUT_DEPTH = 64;
+export declare const INITIAL_STATUS_POLL_MS = 25;
+export declare const MAX_STATUS_POLL_MS = 1000;
+export declare const SHA256: RegExp;

package/dist/replica/command-runtime/constants.js

@@ -0,0 +1,5 @@
+export const MAX_TRANSPORT_RETRIES = 8;
+export const MAX_OUTPUT_DEPTH = 64;
+export const INITIAL_STATUS_POLL_MS = 25;
+export const MAX_STATUS_POLL_MS = 1_000;
+export const SHA256 = /^sha256:[0-9a-f]{64}$/;

package/dist/replica/command-runtime/create.d.ts

@@ -0,0 +1,2 @@
+import type { CommandEntry, ReplicaCommandAuthorityHost, ReplicaCommandRuntime, ReplicaCommandRuntimeOptions, ReplicaCommandTransport } from './types.js';
+export declare function createReplicaCommandRuntime<const TEntries extends Readonly<Record<string, CommandEntry>>>(replica: ReplicaCommandAuthorityHost, transport: ReplicaCommandTransport, entries: TEntries, options?: ReplicaCommandRuntimeOptions): ReplicaCommandRuntime<TEntries>;