@astrosheep/square 0.3.69 → 0.3.71

package/dist/stream.d.ts

@@ -1,10 +1,3 @@
-export type StreamStart = {
-    readonly kind: 'tail';
-    readonly last: number;
-} | {
-    readonly kind: 'after';
-    readonly after: number;
-};
-/** Machine-readable tailing stays available; interactive terminal rendering was retired. */
-export declare function cmdStreamNdjson(squarePath: string, recipient?: string, start?: StreamStart): Promise<void>;
-export declare function cmdStream(squarePath: string): Promise<void>;
+import type { OpenOptions, OperationControl, StreamApplicationOptions, StreamApplicationRecord } from './square-facade.js';
+/** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
+export declare function streamSquare(squarePath: string, options?: StreamApplicationOptions, control?: OperationControl, openOptions?: OpenOptions): AsyncIterable<StreamApplicationRecord>;

package/dist/stream.js

@@ -1,59 +1,88 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { once } from 'node:events';
-import { quoteShell } from './presentation.js';
-import { openSquare, observeSquareChanges } from './square-file-adapter.js';
-import { closeOpenSquare } from './open-square.js';
+import fs from 'node:fs/promises';
+import { SquareError } from './model.js';
+import { observeSquareRevision } from './artifact.js';
+import { openSquare, closeOpenSquare } from './open-square.js';
 import { streamProjection, streamTailProjection } from './views.js';
-/** Machine-readable tailing stays available; interactive terminal rendering was retired. */
-export async function cmdStreamNdjson(squarePath, recipient, start = { kind: 'tail', last: 10 }) {
-    if (!fs.existsSync(squarePath)) {
-        process.stderr.write(`square not found: ${squarePath}\n`);
-        process.exitCode = 2;
-        return;
-    }
-    let cursor = start.kind === 'after' ? start.after : -1;
-    let initial = start.kind === 'tail' ? start : undefined;
-    const observer = await observeSquareChanges(squarePath);
-    try {
-        while (true) {
-            const generation = observer.generation;
-            try {
-                const baseline = await observer.read();
-                const square = await openSquare(squarePath);
-                let hasMore;
+/** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
+export function streamSquare(squarePath, options = {}, control, openOptions = {}) {
+    return {
+        [Symbol.asyncIterator]() {
+            const disposal = new AbortController();
+            const signal = control?.signal === undefined ? disposal.signal : AbortSignal.any([control.signal, disposal.signal]);
+            const iterationControl = { ...control, signal };
+            const records = observe();
+            return {
+                next: () => records.next(),
+                return() {
+                    disposal.abort();
+                    return records.return(undefined);
+                },
+            };
+            async function* observe() {
                 try {
-                    const projection = initial === undefined
-                        ? await streamProjection(square, cursor, recipient)
-                        : await streamTailProjection(square, initial.last, recipient);
-                    for (const item of projection.activities) {
-                        const line = { seq: item.activity.index, square: squarePath, ...item.activity,
-                            ...(item.route === undefined ? {} : { route: item.route }) };
-                        if (!process.stdout.write(`${JSON.stringify(line)}\n`))
-                            await once(process.stdout, 'drain');
+                    signal.throwIfAborted();
+                    try {
+                        await fs.stat(squarePath);
+                    }
+                    catch {
+                        signal.throwIfAborted();
+                        throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
+                    }
+                    signal.throwIfAborted();
+                    const start = options.start ?? { kind: 'tail', last: 10 };
+                    let cursor = start.kind === 'after' ? start.after : -1;
+                    let initial = start.kind === 'tail' ? start : undefined;
+                    const observer = await observeSquareRevision(squarePath);
+                    const close = () => observer.close();
+                    signal.addEventListener('abort', close, { once: true });
+                    try {
+                        signal.throwIfAborted();
+                        while (true) {
+                            const generation = observer.generation;
+                            let baseline;
+                            let projection;
+                            try {
+                                baseline = await observer.read(signal);
+                                const square = await openSquare(squarePath, { ...openOptions, env: openOptions.env ?? {}, signal }, iterationControl);
+                                try {
+                                    projection = initial === undefined
+                                        ? await streamProjection(square, cursor, options.recipient, iterationControl)
+                                        : await streamTailProjection(square, initial.last, options.recipient, iterationControl);
+                                }
+                                finally {
+                                    await closeOpenSquare(square);
+                                }
+                            }
+                            catch (error) {
+                                signal.throwIfAborted();
+                                if (error instanceof SquareError && error.code === 'invalid_args')
+                                    throw error;
+                                // Repair/replacement is a hint, not a reason to scan history on a timer.
+                                await observer.hinted(generation, Infinity, signal);
+                                continue;
+                            }
+                            for (const item of projection.activities) {
+                                signal.throwIfAborted();
+                                yield { seq: item.activity.index, square: squarePath, ...item.activity,
+                                    ...(item.route === undefined ? {} : { route: item.route }) };
+                            }
+                            cursor = projection.cursor;
+                            initial = undefined;
+                            if (!projection.hasMore)
+                                await observer.changed(baseline, Infinity, signal);
+                        }
+                    }
+                    finally {
+                        signal.removeEventListener('abort', close);
+                        observer.close();
                     }
-                    cursor = projection.cursor;
-                    initial = undefined;
-                    hasMore = projection.hasMore;
                 }
-                finally {
-                    await closeOpenSquare(square);
+                catch (error) {
+                    // Iterator disposal is completion; a caller cancellation still rejects the pull.
+                    if (!disposal.signal.aborted || control?.signal?.aborted || error !== signal.reason)
+                        throw error;
                 }
-                if (!hasMore)
-                    await observer.changed(baseline, Infinity);
             }
-            catch {
-                // Repair/replacement is a storage hint, not a reason to scan history on a timer.
-                await observer.hinted(generation, Infinity);
-            }
-        }
-    }
-    finally {
-        observer.close();
-    }
-}
-export async function cmdStream(squarePath) {
-    process.stderr.write('✕ interactive stream was removed\n');
-    process.stderr.write(`square --location ${quoteShell(path.resolve(squarePath))} stream --ndjson\n`);
-    process.exitCode = 2;
+        },
+    };
 }

package/dist/views.d.ts

@@ -1,105 +1,37 @@
 import { type ActivityId } from './square-core.js';
-import { coreParticipants, coreStatus } from './decisions.js';
-import { type DeliveryModel, type PlannedNotification } from './delivery.js';
-import { type ActivitiesOptions, type PublicAct, type SquareState, type StoredAct } from './model.js';
+import { type StoredAct } from './model.js';
 import type { OpenSquare } from './open-square.js';
-import type { Activity, HistoryQuery, OperationControl, ParticipantStatus, SquareSnapshot } from './square-facade.js';
-export interface ActivityPresentation {
-    readonly name: string;
-    readonly roster: readonly string[];
-    readonly pendingPublic: readonly PublicAct[];
-    readonly activities: readonly StoredAct[];
-    readonly state: SquareState;
-    readonly participantCount: number;
-    readonly held: boolean;
-    readonly holdReason?: string;
-    readonly ownActivityCount: number;
-    readonly hardCap: number | null;
-}
-export interface EntryPresentation {
-    readonly joined: boolean;
-    readonly scene: string;
-    readonly context: string;
-    readonly joinContext: string;
-    readonly recentActivities: readonly StoredAct[];
-    readonly state: SquareState;
-    readonly sayNumbers: Readonly<Record<number, number>>;
-    readonly participantCount: number;
-}
-export interface HistoryPresentation {
-    readonly activities: readonly StoredAct[];
-    readonly sayNumbers: Readonly<Record<number, number>>;
-    readonly presenceAnchors: Readonly<Record<number, readonly string[]>>;
-    readonly participantCount: number;
-}
-export interface ListPresentation {
-    readonly context: readonly string[];
-    readonly participants: readonly string[];
-    readonly activities: number;
-}
-export interface StatusPresentation {
-    readonly state: SquareState;
-    readonly status: ReturnType<typeof coreStatus>;
-    readonly latestActNumber?: number;
-}
-export interface WatchPresentation {
-    readonly activities: readonly StoredAct[];
-    readonly state: SquareState;
-    readonly participantCount: number;
-    readonly presence: {
-        readonly participants: ReturnType<typeof coreParticipants>;
-        readonly now: number;
-    };
-    readonly terminalStatus?: 'capped' | 'quorum';
-}
-export interface StreamProjection {
-    readonly activities: readonly {
-        readonly activity: StoredAct;
-        readonly route?: string;
-    }[];
-    readonly cursor: number;
-    readonly hasMore: boolean;
-}
-export interface PendingDeliveryProjection {
-    readonly recipient: string;
-    readonly notifications: readonly PlannedNotification[];
-}
+import type { ActivityFilter, SquareRead } from './ports.js';
+import type { Activity, ApplicationOutcome, ArchiveRecord, HistoryQuery, HistoryApplicationQuery, HistoryContinuation, OperationControl, ParticipantStatus, ParticipantsApplicationData, ParticipantsProjection, SquareSnapshot, RecoveryObservation, EntryPresentation, ListPresentation, StatusApplicationData, StatusProjection, SquareContextProjection, CatchPresence, StreamProjection, EventPresentation } from './square-facade.js';
+export type { RecoveryObservation, EntryPresentation, ListPresentation, CatchPresence, StreamProjection } from './square-facade.js';
+export declare const HISTORY_DEFAULT_LIMIT = 10;
+export declare const HISTORY_MAX_LIMIT = 100;
+export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume", "listen", "ignore"];
 /** The one StoredAct-to-public-Activity field mapping. Rejects read and actorless acts. */
 export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
+/** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
+export declare function selectHistory(facts: SquareRead, query: HistoryApplicationQuery, limit: number | null, kinds: ActivityFilter['kinds']): {
+    continuation?: HistoryContinuation | undefined;
+    activities: StoredAct[];
+    visibleActivities: StoredAct[];
+    totalMatches: number;
+};
+export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
 export declare function history(square: OpenSquare, query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
-export declare function participantHistory(square: OpenSquare, _name: string, query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
 export declare function resolveParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<{
-    readonly name: string;
-    readonly roster: readonly string[];
+    name: string;
 }>;
-export declare function currentParticipant(square: OpenSquare, name: string): Promise<string | undefined>;
+export declare function currentParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<string | undefined>;
 export declare function participants(square: OpenSquare): Promise<ParticipantStatus[]>;
 export declare function snapshot(square: OpenSquare, control?: OperationControl): Promise<SquareSnapshot>;
-export declare function activityPresentation(square: OpenSquare, name: string): Promise<ActivityPresentation>;
-export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null): Promise<EntryPresentation>;
-export declare function historyPresentation(square: OpenSquare, options: ActivitiesOptions): Promise<HistoryPresentation>;
-export declare function participantsPresentation(square: OpenSquare): Promise<ReturnType<typeof coreParticipants>>;
-export declare function listPresentation(square: OpenSquare): Promise<ListPresentation>;
-export declare function statusPresentation(square: OpenSquare): Promise<StatusPresentation>;
-export declare function eventPresentation(square: OpenSquare, id: ActivityId): Promise<{
-    readonly activity: StoredAct;
-    readonly participantCount: number;
-    readonly held: boolean;
-}>;
-export declare function watchPresentation(square: OpenSquare, name: string): Promise<WatchPresentation>;
-export declare function streamProjection(square: OpenSquare | {
-    readonly cell: {
-        read(): Promise<{
-            state: SquareState;
-        }>;
-    };
-}, cursor: number, recipient?: string): Promise<StreamProjection>;
-export declare function streamTailProjection(square: OpenSquare | {
-    readonly cell: {
-        read(): Promise<{
-            state: SquareState;
-        }>;
-    };
-}, last?: number, recipient?: string): Promise<StreamProjection>;
-export declare function pendingDeliveriesFromState(state: SquareState, delivery?: DeliveryModel): readonly PendingDeliveryProjection[];
+export declare function recoveryObservation(square: OpenSquare, name: string, control?: OperationControl): Promise<RecoveryObservation>;
+export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null, control?: OperationControl): Promise<EntryPresentation>;
+type ParticipantQueryContext = Pick<SquareContextProjection, 'location' | 'now' | 'automaticDeliveryAvailable'>;
+export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>;
+export declare function listPresentation(square: OpenSquare, control?: OperationControl): Promise<ListPresentation>;
+export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string): ApplicationOutcome<StatusApplicationData, StatusProjection>;
+export declare function eventPresentation(square: OpenSquare, id: ActivityId, control?: OperationControl): Promise<EventPresentation>;
+export declare function catchPresence(square: OpenSquare, control?: OperationControl): Promise<CatchPresence>;
+export declare function streamProjection(square: OpenSquare, cursor: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;
+export declare function streamTailProjection(square: OpenSquare, last?: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;