[@acaldas/document-model-libs](../README.md) / [Exports](../modules.md) / [Document](Document.md) / utils

# Namespace: utils

[Document](Document.md).utils

## Functions

### createAction

▸ **createAction**<`A`\>(`type`, `input?`, `validator?`): `A`

Helper function to be used by action creators.

**`Remarks`**

Creates an action with the given type and input properties. The input
properties default to an empty object.

**`Throws`**

Error if the type is empty or not a string.

#### Type parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `A` | extends `Action`<`string`\> | Type of the action to be returned. |

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `type` | `A`[``"type"``] | The type of the action. |
| `input?` | `A`[``"input"``] | The input properties of the action. |
| `validator?` | () => { `parse`: (`v`: `unknown`) => `A`  } | - |

#### Returns

`A`

The new action.

#### Defined in

[src/document/utils/base.ts:23](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/base.ts#L23)

___

### createDocument

▸ **createDocument**<`T`, `A`\>(`initialState?`): `Document`<`T`, `A`\>

Builds the initial document state from the provided data.

#### Type parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `T` | `T` | The type of the data. |
| `A` | extends `Action`<`string`\> | The type of the actions. |

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `initialState?` | `Partial`<`Document`<`T`, `A`\>\> & { `data`: `T`  } | The initial state of the document. The `data` property is required, but all other properties are optional. |

#### Returns

`Document`<`T`, `A`\>

The new document state.

#### Defined in

[src/document/utils/base.ts:80](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/base.ts#L80)

___

### createReducer

▸ **createReducer**<`T`, `A`\>(`reducer`, `documentReducer?`): (`state`: `Document`<`T`, `BaseAction` \| `A`\>, `action`: `BaseAction` \| `A`) => `Document`<`T`, `A`\>

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.

#### Type parameters

| Name | Type |
| :------ | :------ |
| `T` | `unknown` |
| `A` | extends `Action`<`string`\> = `Action`<`string`\> |

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `reducer` | `ImmutableReducer`<`T`, `A`\> | `undefined` | The custom reducer to wrap. |
| `documentReducer` | <T, A\>(`state`: `Document`<`T`, `A`\>, `action`: `BaseAction` \| `A`, `customReducer`: `ImmutableReducer`<`T`, `A`\>) => `Document`<`T`, `A`\> | `baseReducer` | Base document reducer that wraps a custom document reducer and handles document-level actions such as undo, redo, prune, and set name. |

#### Returns

`fn`

The new reducer.

▸ (`state`, `action`): `Document`<`T`, `A`\>

##### Parameters

| Name | Type |
| :------ | :------ |
| `state` | `Document`<`T`, `BaseAction` \| `A`\> |
| `action` | `BaseAction` \| `A` |

##### Returns

`Document`<`T`, `A`\>

#### Defined in

[src/document/utils/base.ts:60](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/base.ts#L60)

___

### createZip

▸ **createZip**(`document`): `Promise`<`JSZip`\>

#### Parameters

| Name | Type |
| :------ | :------ |
| `document` | `Document`<`unknown`, `Action`<`string`\>\> |

#### Returns

`Promise`<`JSZip`\>

#### Defined in

[src/document/utils/file.ts:17](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/file.ts#L17)

___

### getLocalFile

▸ **getLocalFile**(`path`): `Promise`<`DocumentFile`\>

Reads an attachment from a file and returns its base64-encoded data and MIME type.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `path` | `string` | The path of the attachment file to read. |

#### Returns

`Promise`<`DocumentFile`\>

A Promise that resolves to an object containing the base64-encoded data and MIME type of the attachment.

#### Defined in

[src/document/utils/file.ts:191](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/file.ts#L191)

___

### getRemoteFile

▸ **getRemoteFile**(`url`): `Promise`<`DocumentFile`\>

Fetches an attachment from a URL and returns its base64-encoded data and MIME type.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `url` | `string` | The URL of the attachment to fetch. |

#### Returns

`Promise`<`DocumentFile`\>

A Promise that resolves to an object containing the base64-encoded data and MIME type of the attachment.

#### Defined in

[src/document/utils/file.ts:174](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/file.ts#L174)

___

### hashAttachment

▸ **hashAttachment**(`data`): `string`

Returns the SHA1 hash of the given attachment data.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `data` | `string` | The base64-encoded data of the attachment to hash. |

#### Returns

`string`

The hash of the attachment data.

#### Defined in

[src/document/utils/file.ts:203](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/file.ts#L203)

___

### hashDocument

▸ **hashDocument**(`state`): `string`

#### Parameters

| Name | Type |
| :------ | :------ |
| `state` | `Document`<`unknown`, `Action`<`string`\>\> |

#### Returns

`string`

#### Defined in

[src/document/utils/base.ts:103](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/base.ts#L103)

___

### hashKey

▸ **hashKey**(`date?`, `randomLimit?`): `string`

#### Parameters

| Name | Type | Default value |
| :------ | :------ | :------ |
| `date?` | `Date` | `undefined` |
| `randomLimit` | `number` | `1000` |

#### Returns

`string`

#### Defined in

[src/document/utils/base.ts:107](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/base.ts#L107)

___

### loadFromFile

▸ **loadFromFile**<`S`, `A`\>(`path`, `reducer`): `Promise`<`Document`<`S`, `BaseAction` \| `A`\>\>

Loads a document from a ZIP file.

**`Remarks`**

This function reads a ZIP file and returns the document state after
applying all the operations. The reducer is used to apply the operations.

**`Throws`**

An error if the initial state or the operations history is not found in the ZIP file.

#### Type parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `S` | `S` | The type of the state object. |
| `A` | extends `Action`<`string`\> | The type of the actions that can be applied to the state object. |

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `path` | `string` | The path to the ZIP file. |
| `reducer` | `Reducer`<`S`, `BaseAction` \| `A`\> | The reducer to apply the operations to the state object. |

#### Returns

`Promise`<`Document`<`S`, `BaseAction` \| `A`\>\>

A promise that resolves to the document state after applying all the operations.

#### Defined in

[src/document/utils/file.ts:100](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/file.ts#L100)

___

### loadFromInput

▸ **loadFromInput**<`S`, `A`\>(`input`, `reducer`): `Promise`<`Document`<`S`, `BaseAction` \| `A`\>\>

#### Type parameters

| Name | Type |
| :------ | :------ |
| `S` | `S` |
| `A` | extends `Action`<`string`\> |

#### Parameters

| Name | Type |
| :------ | :------ |
| `input` | `FileInput` |
| `reducer` | `Reducer`<`S`, `BaseAction` \| `A`\> |

#### Returns

`Promise`<`Document`<`S`, `BaseAction` \| `A`\>\>

#### Defined in

[src/document/utils/file.ts:108](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/file.ts#L108)

___

### saveToFile

▸ **saveToFile**(`document`, `path`, `extension`, `name?`): `Promise`<`string`\>

Saves a document to a ZIP file.

**`Remarks`**

This function creates a ZIP file containing the document's state, operations,
and file attachments. The file is saved to the specified path.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `document` | `Document`<`unknown`, `Action`<`string`\>\> | The document to save to the file. |
| `path` | `string` | The path to save the file to. |
| `extension` | `string` | The extension to use for the file. |
| `name?` | `string` | - |

#### Returns

`Promise`<`string`\>

A promise that resolves to the path of the saved file.

#### Defined in

[src/document/utils/file.ts:61](https://github.com/acaldas/document-model-libs/blob/8be7e70/src/document/utils/file.ts#L61)
