Skip to content

Commit 9869d69

Browse files
AlexVipondAlexVipond
committed
feat(logic): document Transactable
1 parent 57acc1d commit 9869d69

1 file changed

Lines changed: 147 additions & 0 deletions

File tree

‎src/prose/logic/classes/Transactable.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: Transactable
3+
source: true
4+
tests: browser/Transactable.test.ts
5+
publish: true
6+
order: 0
7+
---
8+
9+
`Transactable` is a class that enriches a database name (String), allowing it to:
10+
- Open an [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) database
11+
- Run transactions against an IndexedDB database
12+
- Close an IndexedDB database connection
13+
- Delete an IndexedDB database
14+
15+
16+
:::
17+
## Construct a `Transactable` instance
18+
:::
19+
20+
The `Transactable` constructor accepts two parameters:
21+
22+
::: ariaLabel="Transactable constructor parameters" classes="wide-4"
23+
| Parameter | Type | Required | Description |
24+
| --- | --- | --- | --- |
25+
| `name` | String | yes | The name of the IndexedDB database to be made transactable. |
26+
| `options` | Object | no | Options for the `Transactable` instance. No options are currently accepted. |
27+
:::
28+
29+
30+
:::
31+
## State and methods
32+
:::
33+
34+
::: ariaLabel="Transactable state and methods" classes="wide-3 wide-4 wide-5"
35+
| Property | Type | Description | Parameters | Return value |
36+
| --- | --- | --- | --- | --- |
37+
| `name` | Getter/Setter | See return value | N/A | <p>The `name` (String) passed to the constructor.</p><p>If you assign a value directly to `name`, a setter will pass the new value to `setName`.</p> |
38+
| `status` | Getter | See return value | N/A | <p>The status (String) of the `Transactable` instance.</p><p>See the [Status reference](#status-reference) section for all possible values and their meanings.</p> |
39+
| `db` | Getter | See return value | N/A | The `IDBDatabase` instance. Available after the database has been opened. |
40+
| `transaction` | Getter | See return value | N/A | The current `IDBTransaction` instance. Available while a transaction is in progress via `transact`. |
41+
| `error` | Getter | See return value | N/A | The most recent `Error` encountered, populated after `openerrored`, `transacterrored`, or `deleteerrored`. |
42+
| `setName(newName)` | Function | Stops all active listeners and sets a new database name. | The new `name` (String) | The `Transactable` instance |
43+
| `open(options)` | Function | Opens the IndexedDB database. See the [`open` options](#open-options) section. | See below | The `Transactable` instance |
44+
| `transact(effect, options)` | Function | Runs a transaction against the open database. See the [`transact` options](#transact-options) section. | See below | The `Transactable` instance |
45+
| `readonly(effect, options)` | Function | Shorthand for `transact(effect, { ...options, mode: 'readonly' })`. | Same as `transact`, except `mode` is not accepted. | The `Transactable` instance |
46+
| `readwrite(effect, options)` | Function | Shorthand for `transact(effect, { ...options, mode: 'readwrite' })`. | Same as `transact`, except `mode` is not accepted. | The `Transactable` instance |
47+
| `versionchange(effect, options)` | Function | Shorthand for `transact(effect, { ...options, mode: 'versionchange' })`. | Same as `transact`, except `mode` is not accepted. | The `Transactable` instance |
48+
| `close()` | Function | Closes the IndexedDB database connection. | None | The `Transactable` instance |
49+
| `delete()` | Function | Deletes the IndexedDB database. | None | The `Transactable` instance |
50+
| `stop()` | Function | Stops all active event listeners. | None | The `Transactable` instance |
51+
:::
52+
53+
54+
:::
55+
### `open` options
56+
:::
57+
58+
::: ariaLabel="open options" classes="wide-4"
59+
| Option | Type | Default | Description |
60+
| --- | --- | --- | --- |
61+
| `version` | Number | undefined | The version of the IndexedDB database to open. If omitted, the browser uses the existing version (or 1 for a new database). |
62+
| `upgrade` | Function | undefined | A callback `(db: IDBDatabase) => void` called when the database needs to be upgraded (i.e., when `upgradeneeded` fires). Use this to create or modify object stores and indexes. |
63+
:::
64+
65+
66+
:::
67+
### `transact` options
68+
:::
69+
70+
::: ariaLabel="transact options" classes="wide-4"
71+
| Option | Type | Default | Description |
72+
| --- | --- | --- | --- |
73+
| `storeNames` | String or String[] | `[]` | The name(s) of the object store(s) to include in the transaction. |
74+
| `mode` | String | `'readonly'` | The transaction mode. Valid values are `'readonly'`, `'readwrite'`, and `'versionchange'`. |
75+
| `durability` | String | undefined | The durability hint for the transaction. Passed directly to `IDBDatabase.transaction`. |
76+
:::
77+
78+
79+
:::
80+
### Status reference
81+
:::
82+
83+
::: ariaLabel="Transactable status reference" classes="wide-2"
84+
| Status | Description |
85+
| --- | --- |
86+
| `constructing` | The instance is being constructed. |
87+
| `ready` | Construction is complete; no database has been opened yet. |
88+
| `opening` | `open()` has been called and the database is opening. |
89+
| `opened` | The database has been successfully opened. |
90+
| `openblocked` | The open request was blocked by an existing connection. |
91+
| `openerrored` | The open request encountered an error. |
92+
| `upgradeneeded` | The database requires a version upgrade. The `upgrade` callback runs during this phase, after which status transitions to `opened`. |
93+
| `closing` | `close()` has been called and the database is closing. |
94+
| `closed` | The database connection has been closed. |
95+
| `transacting` | `transact()` has been called and the transaction is in progress. |
96+
| `transacted` | The transaction completed successfully. |
97+
| `transacterrored` | The transaction encountered an error. |
98+
| `transactaborted` | The transaction was aborted. |
99+
| `deleting` | `delete()` has been called and the database is being deleted. |
100+
| `deleteerrored` | The deletion request encountered an error. |
101+
| `deleted` | The database has been successfully deleted. |
102+
:::
103+
104+
105+
:::
106+
## Using with TypeScript
107+
:::
108+
109+
`Transactable` exports the following TypeScript types:
110+
111+
:::
112+
```ts
113+
import type {
114+
TransactableOptions,
115+
TransactableStatus,
116+
TransactEffect,
117+
OpenOptions,
118+
TransactOptions,
119+
} from '@baleada/logic'
120+
```
121+
:::
122+
123+
124+
:::
125+
## API design compliance
126+
:::
127+
128+
::: ariaLabel="Transactable's API design compliance" classes="wide-1 wide-3"
129+
| Spec | Compliance status | Notes |
130+
| --- | --- | --- |
131+
| Access functionality by constructing an instance | <BrandApiDesignSpecCheckmark /> | |
132+
| Constructor accepts two parameters: a piece of state, and an `options` object. | <BrandApiDesignSpecCheckmark /> | |
133+
| Constructor does not access the DOM | <BrandApiDesignSpecCheckmark /> | IndexedDB is not accessed until `open()` is called. |
134+
| Takes the form of a JavaScript Object | <BrandApiDesignSpecCheckmark /> | |
135+
| State and methods are accessible through properties of the object | <BrandApiDesignSpecCheckmark /> | |
136+
| Methods always return the instance | <BrandApiDesignSpecCheckmark /> | |
137+
| Stores the constructor's state in a public getter named after the state's type | <BrandApiDesignSpecCheckmark /> | `name` |
138+
| Has a public method you can use to set a new value for that public getter | <BrandApiDesignSpecCheckmark /> | `setName` |
139+
| Has a setter for that getter so you can assign a new value directly | <BrandApiDesignSpecCheckmark /> | |
140+
| Any other public getters that should be set by you in some cases also have setters and `set<Property>` methods | <BrandApiDesignSpecCheckmark /> | none |
141+
| Has at least one additional getter property that you can't (and shouldn't) set directly | <BrandApiDesignSpecCheckmark /> | `status`, `db`, `transaction`, `error` |
142+
| Has one or more public methods that expose core functionality | <BrandApiDesignSpecCheckmark /> | `open`, `transact`, `readonly`, `readwrite`, `versionchange`, `close`, `delete`, `stop` |
143+
| Either has no side effects or has side effects that can be cleaned up with a `stop` method | <BrandApiDesignSpecCheckmark /> | |
144+
| Uses the sentence template to decide what state type should be accepted by a constructor | <BrandApiDesignSpecCheckmark /> | "A name can be transacted." |
145+
| Constructor does not accept options that only customize the behavior of public methods, it allows those options to be passed to the method itself as a parameter. | <BrandApiDesignSpecCheckmark /> | |
146+
| Named after its core action, proper-cased and suffixed with `able` | <BrandApiDesignSpecCheckmark /> | |
147+
:::

0 commit comments

Comments
 (0)