document-model 4.1.0-dev.7 → 4.1.0-dev.70

package/dist/src/core/ph-types.d.ts

@@ -0,0 +1,256 @@
+import type { AttachmentInput } from "./types.js";
+/**
+ * Information to verify the document creator.
+ */
+export type PHDocumentSignatureInfo = {
+    /**
+     * The public key of the document creator.
+     **/
+    publicKey: JsonWebKey;
+    /** The nonce that was appended to the message to create the signature. */
+    nonce: string;
+};
+/** Meta information about the document. */
+export type PHDocumentMeta = {
+    /** The preferred editor for the document. */
+    preferredEditor?: string;
+};
+/**
+ * The header of a document.
+ */
+export type PHDocumentHeader = {
+    /**
+     * The id of the document.
+     *
+     * This is a Ed25519 signature and is immutable.
+     **/
+    id: string;
+    /**
+     * Information to verify the document creator.
+     *
+     * This is immutable.
+     **/
+    sig: PHDocumentSignatureInfo;
+    /**
+     * The type of the document.
+     *
+     * This is used as part of the signature payload and thus, cannot be changed
+     * after the document header has been created.
+     **/
+    documentType: string;
+    /**
+     * The timestamp of the creation date of the document, in UTC ISO format.
+     *
+     * This is used as part of the signature payload and thus, cannot be changed
+     * after the document header has been created.
+     **/
+    createdAtUtcIso: string;
+    /** The slug of the document. */
+    slug: string;
+    /** The name of the document. */
+    name: string;
+    /** The branch of this document. */
+    branch: string;
+    /**
+     * The revision of each scope of the document. This object is updated every
+     * time any _other_ scope is updated.
+     */
+    revision: {
+        [scope: string]: number;
+    };
+    /**
+     * The timestamp of the last change in the document, in UTC ISO format.
+     **/
+    lastModifiedAtUtcIso: string;
+    /** Meta information about the document. */
+    meta?: PHDocumentMeta;
+};
+/**
+ * The authentication state of the document.
+ *
+ * This has yet to be implemented.
+ */
+export type PHAuthState = {};
+export declare const HASH_ALGORITHM_SHA1 = "sha1";
+export declare const HASH_ALGORITHM_SHA256 = "sha256";
+export declare const HASH_ALGORITHM_SHA512 = "sha512";
+export declare const HASH_ENCODING_BASE64 = "base64";
+export declare const HASH_ENCODING_HEX = "hex";
+/**
+ * Configuration for hashing document state in operations.
+ */
+export type HashConfig = {
+    /** The hashing algorithm to use (e.g., "sha1", "sha256") */
+    algorithm: string;
+    /** The encoding format for the hash output (e.g., "base64", "hex") */
+    encoding: string;
+    /** Optional algorithm-specific parameters */
+    params?: Record<string, unknown>;
+};
+/**
+ * The document state of the document.
+ */
+export type PHDocumentState = {
+    /** The current version of the document. */
+    version: string;
+    /** Hash configuration for operation state verification */
+    hash: HashConfig;
+    /** True if and only if the document has been deleted */
+    isDeleted?: boolean;
+    /** The timestamp when the document was deleted, in UTC ISO format */
+    deletedAtUtcIso?: string;
+    /** Optional: who deleted the document */
+    deletedBy?: string;
+    /** Optional: reason for deletion */
+    deletionReason?: string;
+};
+/**
+ * The base state of the document.
+ */
+export type PHBaseState = {
+    /** Carries authentication information. */
+    auth: PHAuthState;
+    /** Carries information about the document. */
+    document: PHDocumentState;
+};
+/**
+ * A signature of an action.
+ *
+ * This will be refactored in a future release.
+ */
+export type Signature = [string, string, string, string, string];
+/**
+ * A user action signer.
+ */
+export type UserActionSigner = {
+    address: string;
+    networkId: string;
+    chainId: number;
+};
+/**
+ * An app action signer.
+ */
+export type AppActionSigner = {
+    name: string;
+    key: string;
+};
+/**
+ * An action signer.
+ */
+export type ActionSigner = {
+    user: UserActionSigner;
+    app: AppActionSigner;
+    signatures: Signature[];
+};
+/**
+ * The context of an action.
+ */
+export type ActionContext = {
+    /** The index of the previous operation, showing intended ordering. */
+    prevOpIndex?: number;
+    /** The hash of the previous operation, showing intended state. */
+    prevOpHash?: string;
+    /** A nonce, to cover specific signing attacks and to prevent replay attacks from no-ops. */
+    nonce?: string;
+    /** The signer of the action. */
+    signer?: ActionSigner;
+};
+/**
+ * String type representing an attachment in a Document.
+ *
+ * @remarks
+ * Attachment string is formatted as `attachment://<filename>`.
+ */
+export type AttachmentRef = string;
+/**
+ * Defines the basic structure of an action.
+ */
+export type Action = {
+    /** The id of the action. This is distinct from the operation id. */
+    id: string;
+    /** The name of the action. */
+    type: string;
+    /** The timestamp of the action. */
+    timestampUtcMs: string;
+    /** The payload of the action. */
+    input: unknown;
+    /** The scope of the action */
+    scope: string;
+    /**
+     * The attachments included in the action.
+     *
+     * This will be refactored in a future release.
+     */
+    attachments?: AttachmentInput[];
+    /** The context of the action. */
+    context?: ActionContext;
+};
+/**
+ * An operation that was applied to a {@link BaseDocument}.
+ *
+ * @remarks
+ * Wraps an action with an index, to be added to the operations history of a Document.
+ * The `index` field is used to keep all operations in order and enable replaying the
+ * document's history from the beginning.
+ *
+ * @typeParam A - The type of the action.
+ */
+export type Operation = {
+    /** Position of the operation in the history */
+    index: number;
+    /** Timestamp of when the operation was added */
+    timestampUtcMs: string;
+    /** Hash of the resulting document data after the operation */
+    hash: string;
+    /** The number of operations skipped with this Operation */
+    skip: number;
+    /** Error message for a failed action */
+    error?: string;
+    /** The resulting state after the operation */
+    resultingState?: string;
+    /** Unique operation id. This is distinct from the action id and can be undefined and assigned later. */
+    id?: string;
+    /**
+     * The action that was applied to the document to produce this operation.
+     */
+    action: Action;
+};
+/**
+ * The operations history of the document by scope.
+ *
+ * This will be removed in a future release.
+ */
+export type DocumentOperations = Record<string, Operation[]>;
+/**
+ * The base type of a document model.
+ *
+ * @remarks
+ * This type is extended by all Document models.
+ *
+ * @typeParam TState - The type of the document state.
+ */
+export type PHDocument<TState extends PHBaseState = PHBaseState> = {
+    /** The header of the document. */
+    header: PHDocumentHeader;
+    /** The document model specific state. */
+    state: TState;
+    /**
+     * The initial state of the document, enabling replaying operations.
+     *
+     * This will be removed in a future release.
+     */
+    initialState: TState;
+    /**
+     * The operations history of the document.
+     *
+     * This will be removed in a future release.
+     */
+    operations: DocumentOperations;
+    /**
+     * A list of undone operations
+     *
+     * This will be removed in a future release.
+     */
+    clipboard: Operation[];
+};
+//# sourceMappingURL=ph-types.d.ts.map

package/dist/src/core/ph-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ph-types.d.ts","sourceRoot":"","sources":["../../../src/core/ph-types.ts"],"names":[],"mappings":"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"}

package/dist/src/core/ph-types.js

@@ -0,0 +1,15 @@
+///////////////////////////////////////////////////////////////////////////////
+// These are "Reactor V2" types, that have passed through the on-going reactor
+// refactor.
+//
+// Please do not add types to this file that have not been spec'd out in the
+// docs/planning folder in the reactor/ package.
+///////////////////////////////////////////////////////////////////////////////
+// Known hash algorithms (can be extended without breaking changes)
+export const HASH_ALGORITHM_SHA1 = "sha1";
+export const HASH_ALGORITHM_SHA256 = "sha256";
+export const HASH_ALGORITHM_SHA512 = "sha512";
+// Known encodings (can be extended without breaking changes)
+export const HASH_ENCODING_BASE64 = "base64";
+export const HASH_ENCODING_HEX = "hex";
+//# sourceMappingURL=ph-types.js.map

package/dist/src/core/ph-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ph-types.js","sourceRoot":"","sources":["../../../src/core/ph-types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8EAA8E;AAC9E,YAAY;AACZ,EAAE;AACF,4EAA4E;AAC5E,gDAAgD;AAChD,+EAA+E;AA0F/E,mEAAmE;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAQ,CAAC;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAQ,CAAC;AAE9C,6DAA6D;AAC7D,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAC7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC"}

package/dist/src/core/reducer.d.ts

@@ -0,0 +1,61 @@
+import type { Action, DocumentOperations, Operation, PHBaseState, PHDocument, PHDocumentHeader } from "./ph-types.js";
+import type { PruneActionInput, Reducer, ReducerOptions, ReplayDocumentOptions, SignalDispatch, SkipHeaderOperations, StateReducer } from "./types.js";
+export declare function replayOperations<TState extends PHBaseState = PHBaseState>(initialState: TState, clearedOperations: DocumentOperations, stateReducer: StateReducer<TState>, dispatch?: SignalDispatch, header?: PHDocumentHeader, documentReducer?: typeof baseReducer, skipHeaderOperations?: SkipHeaderOperations, options?: ReplayDocumentOptions): PHDocument<TState>;
+/**
+ * Updates the document state based on the provided action.
+ *
+ * @param state The current state of the document.
+ * @param action The action being applied to the document.
+ * @param skip The number of operations to skip before applying the action.
+ * @param reuseLastOperationIndex Whether to reuse the last operation index (used when a an UNDO operation is performed after an existing one).
+ * @returns The updated document state.
+ */
+export declare function updateDocument<TDocument extends PHDocument>(document: TDocument, action: Action, reuseLastOperationIndex?: boolean, skip?: number, operation?: Operation): TDocument;
+/**
+ * Processes an UNDO or REDO action.
+ *
+ * @param document The current state of the document.
+ * @param action The action being applied to the document.
+ * @param skip The number of operations to skip before applying the action.
+ * @returns The updated document, calculated skip value and transformed action (if applied).
+ */
+export declare function processUndoRedo<TState extends PHBaseState = PHBaseState>(document: PHDocument<TState>, action: Action, skip: number): {
+    document: PHDocument<TState>;
+    action: Action;
+    skip: number;
+    reuseLastOperationIndex: boolean;
+};
+/**
+ * Base document reducer that wraps a custom document reducer and handles
+ * document-level actions such as undo, redo, prune, and set name.
+ *
+ * @template TGlobalState - The type of the state of the custom reducer.
+ * @template TAction - The type of the actions of the custom reducer.
+ * @param state - The current state of the document.
+ * @param action - The action object to apply to the state.
+ * @param customReducer - The custom reducer that implements the application logic
+ * specific to the document's state.
+ * @returns The new state of the document.
+ */
+export declare function baseReducer<TState extends PHBaseState = PHBaseState>(document: PHDocument<TState>, action: Action, customReducer: StateReducer<TState>, dispatch?: SignalDispatch, options?: ReducerOptions): PHDocument<TState>;
+/**
+ * Helper function to create a document model reducer.
+ *
+ * @remarks
+ * This function creates a new reducer that wraps the provided `reducer` with
+ * `documentReducer`, adding support for document actions:
+ *   - `SET_NAME`
+ *   - `UNDO`
+ *   - `REDO`
+ *   - `PRUNE`
+ *
+ * It also updates the document-related attributes on every operation.
+ *
+ * @param reducer - The custom reducer to wrap.
+ * @param documentReducer - The document reducer to use.
+ *
+ * @returns The new reducer.
+ */
+export declare function createReducer<TState extends PHBaseState = PHBaseState>(stateReducer: StateReducer<TState>, documentReducer?: typeof baseReducer): Reducer<TState>;
+export declare function pruneOperation<TState extends PHBaseState = PHBaseState>(document: PHDocument<TState>, input: PruneActionInput, wrappedReducer: StateReducer<TState>): PHDocument<TState>;
+//# sourceMappingURL=reducer.d.ts.map

package/dist/src/core/reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducer.d.ts","sourceRoot":"","sources":["../../../src/core/reducer.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EACV,MAAM,EACN,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,UAAU,EACV,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EACV,gBAAgB,EAChB,OAAO,EACP,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACb,MAAM,YAAY,CAAC;AAGpB,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW,EACvE,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,kBAAkB,EACrC,YAAY,EAAE,YAAY,CAAC,MAAM,CAAC,EAClC,QAAQ,CAAC,EAAE,cAAc,EACzB,MAAM,CAAC,EAAE,gBAAgB,EACzB,eAAe,qBAAc,EAC7B,oBAAoB,GAAE,oBAAyB,EAC/C,OAAO,CAAC,EAAE,qBAAqB,GAC9B,UAAU,CAAC,MAAM,CAAC,CAcpB;AA8ED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,SAAS,UAAU,EACzD,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,MAAM,EACd,uBAAuB,UAAQ,EAC/B,IAAI,SAAI,EACR,SAAS,CAAC,EAAE,SAAS,GACpB,SAAS,CAsBX;AA8BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW,EACtE,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX;IACD,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB,EAAE,OAAO,CAAC;CAClC,CASA;AAsGD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW,EAClE,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,YAAY,CAAC,MAAM,CAAC,EACnC,QAAQ,CAAC,EAAE,cAAc,EACzB,OAAO,GAAE,cAAmB,GAC3B,UAAU,CAAC,MAAM,CAAC,CAyKpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW,EACpE,YAAY,EAAE,YAAY,CAAC,MAAM,CAAC,EAClC,eAAe,qBAAc,GAC5B,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,wBAAgB,cAAc,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW,EACrE,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,KAAK,EAAE,gBAAgB,EACvB,cAAc,EAAE,YAAY,CAAC,MAAM,CAAC,GACnC,UAAU,CAAC,MAAM,CAAC,CA+DpB"}