@openmbee/opensysml 0.9.1 → 0.10.0

package/dist/core/edit.d.ts

@@ -0,0 +1,446 @@
+import { type ApplyEditsResponse, type EditOperation } from "../generated/sysml_pb.js";
+import { type ServerInfo } from "./capabilities.js";
+import { Conversion } from "./conversion.js";
+import { EditError, Referrer, type ModelDiagnostic } from "./errors.js";
+import type { ModelSymbol } from "./model.js";
+/** One element an operation targets: a symbol id (FQN) or a ModelSymbol. */
+export type EditTarget = string | ModelSymbol;
+/** A low-level edit operation tuple, as {@link Connection.applyEdits} accepts. */
+export type EditOperationData = readonly unknown[];
+/** One byte range an operation replaced in the source it saw. */
+export declare class AppliedEdit {
+    /** Position of the operation in the editor. */
+    readonly operationIndex: number;
+    /** Element edited, by the id it was named with. */
+    readonly target: string;
+    /** Byte offset where the replacement starts. */
+    readonly offset: number;
+    /** Number of bytes replaced; zero when text was only inserted. */
+    readonly length: number;
+    /** The bytes that were there. */
+    readonly oldText: string;
+    /** What replaced them. */
+    readonly newText: string;
+    /** The document the bytes belong to, named as the parse named it. */
+    readonly document: string;
+    constructor(init: {
+        operationIndex: number;
+        target: string;
+        offset: number;
+        length: number;
+        oldText: string;
+        newText: string;
+        document: string;
+    });
+    toString(): string;
+}
+/** The edited notation of one document of the model. */
+export declare class EditedDocument {
+    /** The document's name as the parse named it. */
+    readonly name: string;
+    /** The edited notation, byte-identical to the source outside the edited spans. */
+    readonly content: string;
+    constructor(init: {
+        name: string;
+        content: string;
+    });
+    toString(): string;
+}
+/** The edited notation, as a {@link Conversion}. */
+export declare class EditResult extends Conversion {
+    /** What each operation changed, grouped by document, in source order within one. */
+    readonly applied: readonly AppliedEdit[];
+    /** The edited notation of every document the edits rewrote, edited document first. */
+    readonly documents: readonly EditedDocument[];
+    constructor(init: {
+        content: string;
+        fromFormat: string;
+        toFormat: string;
+        diagnostics: readonly ModelDiagnostic[];
+        experimental: boolean;
+        experimentalNotice: string;
+        applied: readonly AppliedEdit[];
+        documents: readonly EditedDocument[];
+    });
+}
+/** Name a refusal kind, including one this client's enum has no name for. */
+export declare function failureName(failure: number): string;
+/** Build the error a refusal kind names. */
+export declare function errorForFailure(failure: string, message: string, options?: {
+    diagnostics?: readonly ModelDiagnostic[];
+    referringElements?: readonly string[];
+    referrers?: readonly Referrer[];
+}): EditError;
+/** The referrers of an `ApplyEditsResponse`, each with the document declaring it. */
+export declare function referrersOf(response: ApplyEditsResponse): Referrer[];
+/** Read an `ApplyEditsResponse` as an {@link EditResult}. */
+export declare function editResultOf(response: ApplyEditsResponse, appliedSource?: string): EditResult;
+/** The refusal an `ApplyEditsResponse` carries, as a typed error, or undefined. */
+export declare function editErrorOf(response: ApplyEditsResponse): EditError | undefined;
+/** Chainable action-body items for nested `if` and loop statements. */
+export declare class Body {
+    #private;
+    /** The body items collected so far. */
+    get operations(): readonly unknown[][];
+    /** Emit `first <ref>;`. */
+    addFirst(ref: string): this;
+    /** Emit `then [m] <ref>;` or `then [m] <kind> <action> : <type>;`. */
+    addThen(ref?: string, action?: string, options?: {
+        type?: string;
+        kind?: string;
+        multiplicity?: string;
+    }): this;
+    /** Emit `<kind> <name> : <type>;`. */
+    addAction(name?: string, options?: {
+        type?: string;
+        kind?: string;
+    }): this;
+    /** Emit `accept <payload> [: <type>] [via <via>];` or `then [m] accept ...;`. */
+    addAccept(payload: string, options?: {
+        type?: string;
+        via?: string;
+        then?: boolean;
+        multiplicity?: string;
+    }): this;
+    /** Emit `send <payload> [via <via>] [to <to>];` or `then [m] send ...;`. */
+    addSend(payload: string, options?: {
+        to?: string;
+        via?: string;
+        then?: boolean;
+        multiplicity?: string;
+    }): this;
+    /** Emit `assign <target> := <value>;` or `then [m] assign ...;`. */
+    addAssign(target: string, value: string, options?: {
+        then?: boolean;
+        multiplicity?: string;
+    }): this;
+    /** Emit `if <condition> { <body> } [else { <elseBody> }]` or `then [m] if ...`. */
+    addIf(condition: string, body: Body, elseBody?: Body, options?: {
+        then?: boolean;
+        multiplicity?: string;
+    }): this;
+    /** Emit `while <condition> { <body> } [until <until>];` or `then [m] while ...`. */
+    addWhile(condition: string, body: Body, options?: {
+        until?: string;
+        then?: boolean;
+        multiplicity?: string;
+    }): this;
+    /** Emit `loop { <body> } [until <until>];` or `then [m] loop ...`. */
+    addLoop(body: Body, options?: {
+        until?: string;
+        then?: boolean;
+        multiplicity?: string;
+    }): this;
+    /** Emit `for <variable> [: <type>] in <collection> { <body> }` or `then [m] for ...`. */
+    addFor(variable: string, collection: string, body: Body, options?: {
+        type?: string;
+        then?: boolean;
+        multiplicity?: string;
+    }): this;
+    /** Emit `terminate [<occurrence>];` or `then [m] terminate ...;`. */
+    addTerminate(occurrence?: string, options?: {
+        then?: boolean;
+        multiplicity?: string;
+    }): this;
+    /** Emit `if <guard> then <ref>;`. */
+    addGuardedThen(guard: string, ref: string): this;
+    /** Emit `else <ref>;`. */
+    addElse(ref: string): this;
+}
+/** One name, or several. */
+type Names = string | readonly string[];
+interface MemberOptions {
+    type?: string | undefined;
+    multiplicity?: string | undefined;
+    value?: string | undefined;
+    specializes?: Names | undefined;
+    abstract?: boolean | undefined;
+    redefines?: Names | undefined;
+    default?: boolean | undefined;
+    direction?: string | undefined;
+    metadata?: string | readonly string[] | undefined;
+    expression?: string | undefined;
+    doc?: string | undefined;
+}
+/** Operations to perform on a loaded model, and the call that performs them. */
+export declare class Editor {
+    #private;
+    constructor(modelHash: string, apply: (modelHash: string, operations: readonly EditOperationData[]) => Promise<EditResult>);
+    /** The operations collected so far, in the order they were added. */
+    get operations(): readonly EditOperationData[];
+    /** Whether this editor has been applied. */
+    get applied(): boolean;
+    /** How many operations are collected. */
+    get length(): number;
+    /** Set the value expression of one of the model's features. */
+    setValue(target: EditTarget, value: string): this;
+    /** Rename one of the model's declarations. */
+    rename(target: EditTarget, newName: string): this;
+    /** Add one declaration, using strings for all SysML/KerML notation. */
+    addMember(owner: EditTarget, kind: string, name: string, options?: MemberOptions): this;
+    /** Add an `objective` member, unnamed when `name` is omitted. */
+    addObjective(owner: EditTarget, options?: {
+        name?: string;
+        type?: string;
+    }): this;
+    /** Add `verify <requirement>;` to a verification case or its objective. */
+    addVerify(owner: EditTarget, requirement: string): this;
+    /** Add a `metadata` usage or `@` shorthand with optional values. */
+    addMetadata(owner: EditTarget, metadataType: string, options?: {
+        values?: Readonly<Record<string, string>> | readonly (readonly [string, string])[];
+        name?: string;
+        about?: string | readonly string[];
+        shorthand?: boolean;
+    }): this;
+    /** Add a metadata prefix to an existing declaration. */
+    addMetadataPrefix(target: EditTarget, metadataType: string): this;
+    /** Add `doc /* body *\/` as the first body member of a declaration. */
+    addDocumentation(target: EditTarget, body: string, options?: {
+        name?: string;
+        locale?: string;
+        replace?: boolean;
+    }): this;
+    /** Add `comment [name] [about a, b] [locale "..."] /* body *\/` to a body. */
+    addComment(owner: EditTarget, body: string, options?: {
+        name?: string;
+        about?: readonly EditTarget[];
+        locale?: string;
+    }): this;
+    /** Write the line note `// text` on its own line above a declaration. */
+    addNote(target: EditTarget, text: string): this;
+    /** Add a `satisfy` usage to a body that admits behavior usages. */
+    addSatisfy(owner: EditTarget, requirement: string, options?: {
+        by?: string;
+        asserted?: boolean;
+        negated?: boolean;
+    }): this;
+    /** Add a `require` or `assume` constraint to a requirement-like body. */
+    addRequirementConstraint(owner: EditTarget, kind: string, expression: string, name?: string): this;
+    /** Add a transition with optional trigger, guard and effect clauses. */
+    addTransition(owner: EditTarget, source: string, target: string, options?: {
+        name?: string;
+        trigger?: string;
+        guard?: string;
+        effect?: string;
+    }): this;
+    /** Add an entry transition to target in a state body. */
+    addEntryTransition(owner: EditTarget, target: string): this;
+    /** Emit `first <ref>;`. */
+    addFirst(owner: EditTarget, ref: string, options?: {
+        after?: string;
+    }): this;
+    /** Emit `then [m] <ref>;` or `then [m] <kind> <name> : <type>;`. */
+    addThen(owner: EditTarget, options?: {
+        ref?: string;
+        action?: string;
+        type?: string;
+        after?: string;
+        kind?: string;
+        multiplicity?: string;
+    }): this;
+    /** Emit `then [m] accept <payload> [: <type>] [via <via>];`. */
+    addAccept(owner: EditTarget, payload: string, options?: {
+        type?: string;
+        via?: string;
+        then?: boolean;
+        multiplicity?: string;
+        after?: string;
+    }): this;
+    /** Emit `then [m] send <payload> [via <via>] [to <to>];`. */
+    addSend(owner: EditTarget, payload: string, options?: {
+        to?: string;
+        via?: string;
+        then?: boolean;
+        multiplicity?: string;
+        after?: string;
+    }): this;
+    /** Emit `then [m] assign <target> := <value>;`. */
+    addAssign(owner: EditTarget, target: string, value: string, options?: {
+        then?: boolean;
+        multiplicity?: string;
+        after?: string;
+    }): this;
+    /** Emit `then [m] if <condition> { <body> } [else { <elseBody> }]`. */
+    addIf(owner: EditTarget, condition: string, body: Body, elseBody?: Body, options?: {
+        then?: boolean;
+        multiplicity?: string;
+        after?: string;
+    }): this;
+    /** Emit `then [m] while <condition> { <body> } [until <until>];`. */
+    addWhile(owner: EditTarget, condition: string, body: Body, options?: {
+        until?: string;
+        then?: boolean;
+        multiplicity?: string;
+        after?: string;
+    }): this;
+    /** Emit `then [m] loop { <body> } [until <until>];`. */
+    addLoop(owner: EditTarget, body: Body, options?: {
+        until?: string;
+        then?: boolean;
+        multiplicity?: string;
+        after?: string;
+    }): this;
+    /** Emit `then [m] for <variable> [: <type>] in <collection> { <body> }`. */
+    addFor(owner: EditTarget, variable: string, collection: string, body: Body, options?: {
+        type?: string;
+        then?: boolean;
+        multiplicity?: string;
+        after?: string;
+    }): this;
+    /** Emit `then [m] terminate [<occurrence>];`. */
+    addTerminate(owner: EditTarget, occurrence?: string, options?: {
+        then?: boolean;
+        multiplicity?: string;
+        after?: string;
+    }): this;
+    /** Emit `if <guard> then <ref>;`. */
+    addGuardedThen(owner: EditTarget, guard: string, ref: string, options?: {
+        after?: string;
+    }): this;
+    /** Emit `else <ref>;`. */
+    addElse(owner: EditTarget, ref: string, options?: {
+        after?: string;
+    }): this;
+    /** Add an import declaration to a namespace body or the document root. */
+    addImport(owner: EditTarget, target: string, options?: {
+        visibility?: string;
+        recursive?: boolean;
+        all?: boolean;
+        filter?: string | readonly string[];
+    }): this;
+    /** Add a `require constraint` to a requirement-like body. */
+    addRequireConstraint(owner: EditTarget, expression: string, name?: string): this;
+    /** Add an `assume constraint` to a requirement-like body. */
+    addAssumeConstraint(owner: EditTarget, expression: string, name?: string): this;
+    /** Add a connection-like usage between two feature references. */
+    addConnection(owner: EditTarget, kind: string, from: string, to: string, options?: {
+        name?: string;
+        type?: string;
+    }): this;
+    /** Add an `allocation ... allocate from to` usage. */
+    addAllocation(owner: EditTarget, from: string, to: string, options?: {
+        name?: string;
+        type?: string;
+    }): this;
+    /** Add a `flow ... from from to` usage. */
+    addFlow(owner: EditTarget, from: string, to: string, options?: {
+        name?: string;
+        type?: string;
+    }): this;
+    /** Add a `succession ... first from then to` usage. */
+    addSuccession(owner: EditTarget, from: string, to: string, options?: {
+        name?: string;
+        type?: string;
+    }): this;
+    /** Delete a declaration, optionally removing declarations that refer to it. */
+    delete(target: EditTarget, options?: {
+        cascade?: boolean;
+    }): this;
+    /** Move a declaration into another namespace of the same document. */
+    move(target: EditTarget, owner: EditTarget): this;
+    /** Have the service perform these operations and return the edited model. */
+    apply(): Promise<EditResult>;
+    toString(): string;
+    addPackage(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addPartDef(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addPart(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addAttributeDef(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addAttribute(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addItemDef(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addItem(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addPortDef(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addPort(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addClass(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addStruct(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addDatatype(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addClassifier(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addFeature(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addAssoc(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addBehavior(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addFunction(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addPredicate(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addInteraction(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addMetaclass(owner: EditTarget, name: string, options?: MemberOptions): this;
+    /** Add a `calc def` with input parameters and an optional result. */
+    addCalcDef(owner: EditTarget, name: string, options?: MemberOptions & {
+        inputs?: readonly (readonly [string, string])[];
+        returnType?: string;
+        returnExpression?: string;
+    }): this;
+    /** Add a `calc` with input parameters and an optional result. */
+    addCalc(owner: EditTarget, name: string, options?: MemberOptions & {
+        inputs?: readonly (readonly [string, string])[];
+        returnType?: string;
+        returnExpression?: string;
+    }): this;
+    /** Add a directional parameter usage. */
+    addParameter(owner: EditTarget, direction: string, name: string, options?: MemberOptions & {
+        kind?: string;
+    }): this;
+    /** Add a return parameter member. */
+    addReturn(owner: EditTarget, options?: MemberOptions & {
+        name?: string;
+    }): this;
+    /** Add an `action def` with input and output parameters. */
+    addActionDef(owner: EditTarget, name: string, options?: MemberOptions & {
+        inputs?: readonly (readonly [string, string])[];
+        outputs?: readonly (readonly [string, string])[];
+    }): this;
+    /** Add an `action` with input and output parameters. */
+    addAction(owner: EditTarget, name: string, options?: MemberOptions & {
+        inputs?: readonly (readonly [string, string])[];
+        outputs?: readonly (readonly [string, string])[];
+    }): this;
+    /** Add a `perform action name : Type` usage. */
+    addPerformAction(owner: EditTarget, name: string, options?: MemberOptions): this;
+    /** Add a `perform <action>;` usage named by its referenced action. */
+    addPerform(owner: EditTarget, action: string, options?: {
+        doc?: string;
+    }): this;
+    /** Add an `exhibit state` usage. */
+    addExhibitState(owner: EditTarget, name: string, options?: {
+        type?: string;
+    }): this;
+    /** Add an `exhibit <state>;` usage named by its referenced state. */
+    addExhibit(owner: EditTarget, state: string): this;
+    /** Add an `entry`, `do` or `exit` action to a state body. */
+    addStateAction(owner: EditTarget, kind: string, name: string, options?: {
+        type?: string;
+    }): this;
+    addStateDef(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addState(owner: EditTarget, name: string, options?: MemberOptions): this;
+    /** Add a `constraint def`; `expression` writes `{ … }`, `value` writes `= …`. */
+    addConstraintDef(owner: EditTarget, name: string, options?: MemberOptions): this;
+    /** Add a `constraint`; `expression` writes `{ … }`, `value` writes `= …`. */
+    addConstraint(owner: EditTarget, name: string, options?: MemberOptions): this;
+    /** Add an asserted constraint usage, optionally negated. */
+    addAssertConstraint(owner: EditTarget, options?: {
+        name?: string;
+        type?: string;
+        expression?: string;
+        negated?: boolean;
+    }): this;
+    /** Add an anonymous `assert` usage; the assertion is not named by ref. */
+    addAssert(owner: EditTarget, ref: string, options?: {
+        negated?: boolean;
+    }): this;
+    addRequirementDef(owner: EditTarget, name: string, options?: MemberOptions): this;
+    addRequirement(owner: EditTarget, name: string, options?: MemberOptions): this;
+}
+/** Translates edit tuples into an `ApplyEditsRequest`'s operations, gating capabilities. */
+export declare class EditRequestBuilder {
+    #private;
+    constructor(info: ServerInfo);
+    /** The operations the tuples describe, and the capabilities they need. A
+     * wire `EditOperation` passes through as written — how a caller sends an
+     * operation the tuple form cannot write — gated on the fields it carries. */
+    build(operations: readonly (EditOperationData | EditOperation)[]): {
+        operations: EditOperation[];
+        capabilities: string[];
+    };
+    add(operationData: EditOperationData | EditOperation): EditOperation;
+    /** Gate an operation already in wire form on the fields it carries. */
+    wire(operation: EditOperation): EditOperation;
+    finish(): string[];
+}
+export {};