@hydranium/core 1.0.0-next.37 → 1.0.0-next.371

package/src/langium/model-service/index.ts

@@ -7,4 +7,6 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './model-events.js';
 export * from './model-service.js';
+export * from './client-session.js';

package/src/langium/model-service/model-events.ts

@@ -0,0 +1,82 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type CanonicalUri } from '@hydranium/protocol';
+import { type AstNode, type DocumentState } from '@hydranium/langium';
+import { type AstDocumentSavedEvent, type AstDocumentUpdatedEvent } from '../../documents/ast-document-manager.js';
+import { type DocumentDirtyChangedEvent } from '../../documents/dirty-state-tracker.js';
+import { type DocumentReleasedEvent } from '../../documents/hydranium-text-documents.js';
+import { type AstDiagnostic } from '../validation/document-validator.js';
+
+/** Which documents a `ModelService` subscription hears about. */
+export interface ModelEventFilter {
+   /** One document, in any spelling; matched by canonical form. Absent for every document. */
+   readonly uri?: string;
+}
+
+/** A {@link ModelEventFilter} for an event a build phase fires. */
+export interface ModelPhaseFilter extends ModelEventFilter {
+   /** Defaults to `Validated`. */
+   readonly phase?: DocumentState;
+}
+
+/**
+ * A document reaching {@link phase} in a build.
+ *
+ * `document` holds for the listener's synchronous run: its root is the one the
+ * build carried to the phase, and at `Validated` its diagnostics are that
+ * build's, copied. A later build can unlink that root in place or replace it,
+ * so a listener that awaits first reads the document again through the phase
+ * reads or `snapshot`.
+ *
+ * Below `Validated` the document carries no diagnostics: any it held would be
+ * an earlier build's.
+ */
+export interface ModelUpdatedEvent<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> extends AstDocumentUpdatedEvent<
+   TAst,
+   TDiagnostic
+> {
+   readonly phase: DocumentState;
+}
+
+/**
+ * The documents one build carried to {@link phase}. Not fired for a cancelled
+ * build. The build that takes over redoes only the documents the cancelled one
+ * left unfinished, so a document it had already completed is reported by no
+ * event until a later build touches it.
+ */
+export interface ModelsBuiltEvent {
+   readonly uris: readonly CanonicalUri[];
+   readonly phase: DocumentState;
+}
+
+/**
+ * A document's file was removed. No build reaches a deleted document, so no
+ * {@link ModelUpdatedEvent} reports it.
+ */
+export interface ModelDeletedEvent {
+   readonly uri: CanonicalUri;
+   /**
+    * The session whose `delete` removed the file; the unknown-client id for a
+    * file removed outside any session, as a file watcher reports one.
+    */
+   readonly sourceClientId: string;
+}
+
+/** A document was saved: the AST manager's event, as `ModelService` hands it out. */
+export type ModelSavedEvent<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> = AstDocumentSavedEvent<
+   TAst,
+   TDiagnostic
+>;
+
+/** A document's text started or stopped differing from its file: the store's event, as `ModelService` hands it out. */
+export type ModelDirtyChangedEvent = DocumentDirtyChangedEvent;
+
+/** A document no client has open any more was released: the store's event, as `ModelService` hands it out. */
+export type ModelReleasedEvent = DocumentReleasedEvent;