|
2 | 2 |
|
3 | 3 | #### contents |
4 | 4 |
|
5 | | -- [SDK embedded docs](#start-sdk-embedded-documentation) |
6 | | -- [Container initialization](#container-initialization) |
| 5 | +- [start-sdk embedded docs](#start-sdk-embedded-docs) |
| 6 | +- [Container init](#container-init) |
7 | 7 | - [File Models](#file-models) |
8 | 8 |
|
9 | | -## start-sdk embedded documentation |
| 9 | +## start-sdk embedded docs |
10 | 10 |
|
11 | 11 | When working with start-sdk in a package codebase, hover states reveal descriptions, type definitions, and example usages of just about everything. If you are wondering what a function does or how to use, hovering over the function name. If you are wondering what attributes can be included in an object, press `ctrl + space` inside the object. |
12 | 12 |
|
13 | | -## Container initialization |
| 13 | +### Container init |
14 | 14 |
|
15 | | -### Service containers are built/created: |
| 15 | +Service containers are initialized when: |
16 | 16 |
|
17 | | -- When the service is freshly installed. |
18 | | -- When the service is updated or downgraded. |
19 | | -- On StartOS boot. |
20 | | -- If the user manually triggers a rebuild. |
| 17 | +- When the service is freshly installed |
| 18 | +- When the service is updated or downgraded |
| 19 | +- On StartOS boot |
| 20 | +- If the user manually triggers a rebuild |
21 | 21 |
|
22 | | -### Service container initialization sequence. Each of the below are functions in start-sdk: |
| 22 | +## File Models |
23 | 23 |
|
24 | | -This means, for example, that the results of `setupDependencies()` are not available to `setupInterfaces()` on initialization. |
| 24 | +Many services have configuration files, such as a config.toml. With start-sdk, these files can and should be represented as "File Models" in the file-models directory. Here you create a Typescript definition of the file, providing type protection throughout the codebase. File Models can also enforce types _at runtime_. For example, if a json file expects a "name" key to be a string and the user uses SSH to enter a number instead, you can coerce the value back to a string and protect the user from themselves. File Models provide automatic parsing/serialization for `.json`, `.yaml`, `.toml`, `.ini`, and `.env`. For custom file types (e.g. `.conf`) you can provide a custom parser/serializer. |
25 | 25 |
|
26 | | -1. `initStore()`: (runs once ever, only on fresh install) |
27 | | -1. `setupPreInstall()` (run once ever, only on fresh install) |
28 | | -1. `setupInterfaces()` |
29 | | -1. `Any actions passed to Actions.of()` |
30 | | -1. `setupExposeStore()` |
31 | | -1. `setupDependencies()` |
32 | | -1. `setupPostInstall()` (runs once ever, only on fresh install) |
33 | | -1. `The [up or down] migration of the first version provided to VersionGraph.of()` (update only) |
34 | | -1. `setupMain()` |
| 26 | +### Reading files |
35 | 27 |
|
36 | | -## File Models |
| 28 | +File Models have a `read()` method that take an optional mapping if you only care to read a subset of the file. |
37 | 29 |
|
38 | | -Many services have configuration files, such as a config.toml. With start-sdk, these files can and should be represented as a File Model in the file-models directory. Here you create a Typescript definition of the file, providing type protection throughout the codebase. File Models can also enforce types _at runtime_. For example, if a json file expects a "name" key to be a string and the user uses SSH to enter a number instead, you can coerce the value back to a string and protect the user from themselves. File Models provide automatic parsing/serialization for `.json`, `.yaml`, `.toml`, `.ini`, and `.env`. For custom file types (e.g. `.conf`) you can provide your own parser/serializer. |
| 30 | +- `FileModel.read().once()` will return the entire file |
| 31 | +- `FileModel.read(f => f.users).once()` will return only the contents of "users". |
39 | 32 |
|
40 | | -## Reading File Models and Store values |
| 33 | +### Options for reading |
41 | 34 |
|
42 | 35 | When you access a File Model or Store value, you must choose between: |
43 | 36 |
|
44 | 37 | - `.once()`: returns the parsed file or Store value and nothing else. |
45 | | -- `.const()`: returns the parsed file or Store value, and registers an OS task to re-run the context function if the file or value changes. For example, a `.const()` used to get a "name" value from the Store in `setupInterfaces()` would result in `setupInterfaces()` re-running if the "name" value changes. |
46 | | -- `.onChange()`: registers an OS tak to run a callback function that accepts the new file or value. For example, `.onChange((newFileOrValue) => { // do stuff })` |
47 | | -- `watch()`: returns an async iterator of the new file or value. @TODO provide an example |
| 38 | +- `.const(effects)`: returns the parsed file or Store value, and registers an OS task to re-run the context function if the file or nested value of interest changes. For example, if you did `FileModel.read(f => f.name).const(effects)` in `setupInterfaces()`, then `setupInterfaces()` would re-run whenever "name" changes. |
| 39 | +- `.onChange(effects)`: registers an OS tak to run a callback function that accepts the new file or value. For example, `FileModel.read().onChange((file) => { // do stuff })` |
| 40 | +- `watch(effects)`: returns an async iterator of the new file or value. |
0 commit comments