SearSuite
← All packages

@searsuite/sear-plugin-export

Versioned export envelopes, document-state codec registries, and durable persistence boundaries.

Document codecs

classDocumentStateCodecRegistry
class DocumentStateCodecRegistry<TState>

Registry that composes document-state modules without central field enumeration.

constructorDocumentStateCodecRegistry<TState>(): DocumentStateCodecRegistry<TState>
methoddeserialize(modules: readonly SearDocumentStateModuleFile[], path: string): Partial<TState>

Deserializes registered modules into one partial document state.

methodregister(codec: DocumentStateCodec<TState>): this

Registers a module codec. Duplicate keys are rejected.

methodregisterContribution(contribution: DocumentStateModuleContribution<unknown, object>): this

Registers the codec from a plugin-owned document-state contribution.

methodserialize(state: TState): SearDocumentStateModuleFile[]

Serializes every registered module whose codec returns a payload.

interfaceDocumentStateCodec
interface DocumentStateCodec<TState>

Codec contributed by the owner of one document-state module.

propertyreadonly key: string

Stable module key written to persisted files.

methoddeserialize(payload: JsonValue, path: string): Partial<TState>

Restores the module-owned part of a document state.

methodserialize(state: TState): unknown

Serializes the module-owned part of a document state.

interfaceDocumentStateModuleContribution
interface DocumentStateModuleContribution<TOwnerState, TDocumentState>

Export contribution owned by one document-state owner.

propertyreadonly codec: DocumentStateCodec<TDocumentState>

JSON codec used for this module in stable export files.

propertyreadonly key: string

Stable module key written to persisted files.

methodcapture(ownerState: TOwnerState): Partial<TDocumentState> | undefined

Captures this owner state into the aggregate document-state snapshot.

Export files

classExportError
class ExportError extends SearError

Error thrown when a persisted workbook payload cannot be encoded or decoded.

constructorExportError(code: ExportErrorCode, message: string, details?: SearErrorDetails): ExportError
propertyreadonly code: ExportErrorCode

Stable machine-readable error code.

Inherited members 9

Inherited from SearError.

interfaceSearDocumentStateModuleFile

One registered document-state module in a stable export file.

propertyreadonly key: string

Stable module key owned by the state owner, such as sheet.data.

propertyreadonly payload: JsonValue

Module-owned JSON payload.

interfaceSearSheetDocumentFile

Stable persisted representation of one Sheet document state.

propertyreadonly kind: "sheet"

Sheet payload kind.

propertyreadonly modules: readonly SearDocumentStateModuleFile[]

Registered document-state modules.

interfaceSearWorkbookFile
interface SearWorkbookFile<TSheetDescriptor>

Stable persisted representation of a Workbook document state.

propertyreadonly format: "searsuite.workbook"

Stable file-format identifier.

propertyreadonly workbook: { formulaBindings?: readonly SearFormulaBindingFile[]; id: string; metadata?: Readonly<Record<string, JsonValue>>; sheets: readonly TSheetDescriptor[]; sheetStates: Readonly<Record<string, SearSheetDocumentFile>> }

Persisted workbook document state.

typeExportErrorCode
type ExportErrorCode = typeof ExportErrorCode[keyof typeof ExportErrorCode] ExportErrorCode: { codecNotFound: "SEAR_EXPORT_CODEC_NOT_FOUND"; duplicateCodec: "SEAR_EXPORT_DUPLICATE_CODEC"; invalidFormat: "SEAR_EXPORT_INVALID_FORMAT" }

Machine-readable export error code type.

variableSearWorkbookFileFormat
SearWorkbookFileFormat: "searsuite.workbook"

Current stable workbook JSON format identifier.

variableExportErrorCodeValue
ExportErrorCodeValue: { codecNotFound: "SEAR_EXPORT_CODEC_NOT_FOUND"; duplicateCodec: "SEAR_EXPORT_DUPLICATE_CODEC"; invalidFormat: "SEAR_EXPORT_INVALID_FORMAT" }

Stable machine-readable error codes owned by the export plugin.

JSON values

typeJsonValue
type JsonValue = null | boolean | number | string | readonly JsonValue[] | { }

JSON-compatible scalar or object value.

functioncloneJsonRecord
cloneJsonRecord(value: Readonly<Record<string, unknown>> | undefined, path: string): Readonly<Record<string, JsonValue>> | undefined

Narrows a runtime value to a JSON-compatible metadata record.

functioncloneJsonValue
cloneJsonValue<TValue>(value: TValue, path?: string): TValue

Clones a JSON-compatible value and rejects values that cannot be persisted as JSON.

functionreadRecord
readRecord(value: unknown, path: string): Record<string, unknown>

Narrows a runtime value to a plain object.