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

# Namespace: utils

[Document](Document.md).utils

## Table of contents

### Type Aliases

- [FileInput](Document.utils.md#fileinput)

### Functions

- [createAction](Document.utils.md#createaction)
- [createDocument](Document.utils.md#createdocument)
- [createReducer](Document.utils.md#createreducer)
- [createZip](Document.utils.md#createzip)
- [getLocalFile](Document.utils.md#getlocalfile)
- [getRemoteFile](Document.utils.md#getremotefile)
- [hashAttachment](Document.utils.md#hashattachment)
- [hashDocument](Document.utils.md#hashdocument)
- [hashKey](Document.utils.md#hashkey)
- [loadFromFile](Document.utils.md#loadfromfile)
- [loadFromInput](Document.utils.md#loadfrominput)
- [saveToFile](Document.utils.md#savetofile)
- [saveToFileHandle](Document.utils.md#savetofilehandle)

## Type Aliases

### FileInput

Ƭ **FileInput**: `string` \| `number`[] \| `Uint8Array` \| `ArrayBuffer` \| `Blob`

#### Defined in

[src/document/utils/file.ts:16](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L16)

## Functions

### createAction

▸ **createAction**<`A`\>(`type`, `input?`, `attachments?`, `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`](Document.md#action)<`string`, `unknown`\> | 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. |
| `attachments?` | [`DocumentFile`](Document.md#documentfile) & { `hash`: `string`  }[] | - |
| `validator?` | () => { `parse`: (`v`: `unknown`) => `A`  } | - |

#### Returns

`A`

The new action.

#### Defined in

[src/document/utils/base.ts:28](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/base.ts#L28)

___

### createDocument

▸ **createDocument**<`T`, `A`\>(`initialState?`): [`Document`](Document.md#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`](Document.md#action)<`string`, `unknown`\> | The type of the actions. |

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `initialState?` | `Partial`<[`ExtendedState`](Document.md#extendedstate)<`T`\>\> | The initial state of the document. The `data` property is required, but all other properties are optional. |

#### Returns

[`Document`](Document.md#document)<`T`, `A`\>

The new document state.

#### Defined in

[src/document/utils/base.ts:87](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/base.ts#L87)

___

### createReducer

▸ **createReducer**<`T`, `A`\>(`reducer`, `documentReducer?`): [`Reducer`](Document.md#reducer)<`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`](Document.md#action)<`string`, `unknown`\> = [`Action`](Document.md#action)<`string`, `unknown`\> |

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `reducer` | [`ImmutableStateReducer`](Document.md#immutablestatereducer)<`T`, `A`\> | `undefined` | The custom reducer to wrap. |
| `documentReducer` | <T, A\>(`document`: [`Document`](Document.md#document)<`T`, `A`\>, `action`: [`BaseAction`](Document.md#baseaction) \| `A`, `customReducer`: [`ImmutableStateReducer`](Document.md#immutablestatereducer)<`T`, `A`\>) => [`Document`](Document.md#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

[`Reducer`](Document.md#reducer)<`T`, `A`\>

The new reducer.

#### Defined in

[src/document/utils/base.ts:67](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/base.ts#L67)

___

### createZip

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

#### Parameters

| Name | Type |
| :------ | :------ |
| `document` | [`Document`](Document.md#document)<`unknown`, [`Action`](Document.md#action)<`string`, `unknown`\>\> |

#### Returns

`Promise`<`JSZip`\>

#### Defined in

[src/document/utils/file.ts:18](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L18)

___

### getLocalFile

▸ **getLocalFile**(`path`): `Promise`<[`DocumentFile`](Document.md#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`](Document.md#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:211](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L211)

___

### getRemoteFile

▸ **getRemoteFile**(`url`): `Promise`<[`DocumentFile`](Document.md#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`](Document.md#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:194](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L194)

___

### 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:223](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L223)

___

### hashDocument

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

#### Parameters

| Name | Type |
| :------ | :------ |
| `document` | [`Document`](Document.md#document)<`unknown`, [`Action`](Document.md#action)<`string`, `unknown`\>\> |

#### Returns

`string`

#### Defined in

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

___

### 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:112](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/base.ts#L112)

___

### loadFromFile

▸ **loadFromFile**<`S`, `A`\>(`path`, `reducer`): `Promise`<[`Document`](Document.md#document)<`S`, `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`](Document.md#action)<`string`, `unknown`\> | 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`](Document.md#reducer)<`S`, `A`\> | The reducer to apply the operations to the state object. |

#### Returns

`Promise`<[`Document`](Document.md#document)<`S`, `A`\>\>

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

#### Defined in

[src/document/utils/file.ts:112](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L112)

___

### loadFromInput

▸ **loadFromInput**<`S`, `A`\>(`input`, `reducer`): `Promise`<[`Document`](Document.md#document)<`S`, `A`\>\>

#### Type parameters

| Name | Type |
| :------ | :------ |
| `S` | `S` |
| `A` | extends [`Action`](Document.md#action)<`string`, `unknown`\> |

#### Parameters

| Name | Type |
| :------ | :------ |
| `input` | [`FileInput`](Document.utils.md#fileinput) |
| `reducer` | [`Reducer`](Document.md#reducer)<`S`, `A`\> |

#### Returns

`Promise`<[`Document`](Document.md#document)<`S`, `A`\>\>

#### Defined in

[src/document/utils/file.ts:120](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L120)

___

### 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`](Document.md#document)<`unknown`, [`Action`](Document.md#action)<`string`, `unknown`\>\> | 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:62](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L62)

___

### saveToFileHandle

▸ **saveToFileHandle**(`document`, `input`): `Promise`<`void`\>

#### Parameters

| Name | Type |
| :------ | :------ |
| `document` | [`Document`](Document.md#document)<`unknown`, [`Action`](Document.md#action)<`string`, `unknown`\>\> |
| `input` | `FileSystemFileHandle` |

#### Returns

`Promise`<`void`\>

#### Defined in

[src/document/utils/file.ts:86](https://github.com/acaldas/document-model-libs/blob/d48c213/src/document/utils/file.ts#L86)
