heim 0.1.0-alpha.3 → 0.1.0-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/types.d.ts +244 -129
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "heim",
3
- "version": "0.1.0-alpha.3",
3
+ "version": "0.1.0-alpha.4",
4
4
  "description": "The library to create heim.ts files for heim apps.",
5
5
  "license": "Apache-2.0",
6
6
  "author": {
package/types.d.ts CHANGED
@@ -4,14 +4,21 @@ declare global {
4
4
  /**
5
5
  * This is the main entry point for defining an application using the heim TypeScript library.
6
6
  */
7
- function defineApp(config: AppConfig): AppConfig;
7
+ function defineApp<const I extends Inputs = Record<string, never>>(
8
+ config: AppConfig<I>,
9
+ ): AppConfig<I>;
8
10
 
9
11
  // Types
10
- type AppConfig = {
12
+ type AppConfig<I extends Inputs = Record<string, never>> = {
11
13
  /**
12
14
  * The metadata is the descriptive information of the app such as its name, version, description, and other relevant information.
13
15
  */
14
16
  metadata: Metadata;
17
+ /**
18
+ * The inputs declare the questions the user is asked during installation. Answers are stored and reused on later runs,
19
+ * so updates run unattended.
20
+ */
21
+ inputs?: I;
15
22
  /**
16
23
  * The user interface configuration defines how the app's UI should be set up, including the services it provides, the ports it uses, and whether it requires authentication.
17
24
  * It is optional, and if not provided, the app will only render the console as the user interface.
@@ -20,7 +27,7 @@ declare global {
20
27
  /**
21
28
  * The compose configuration defines the Docker Compose specification for the app, including the services, volumes, networks, and other Docker resources that the app requires to run.
22
29
  */
23
- compose: Compose | ((ctx: ComposeContext) => Compose);
30
+ compose: Compose | ((ctx: ComposeContext<I>) => Compose);
24
31
  /**
25
32
  * The backup configuration defines which volumes of the app should be backed up. It also allows specifying a custom backup command.
26
33
  */
@@ -28,7 +35,7 @@ declare global {
28
35
  /**
29
36
  * The restore configuration defines how to restore the app from a backup, including any custom restore commands that need to be executed before the restore process.
30
37
  */
31
- restore?: Restore | ((ctx: RestoreContext) => Restore);
38
+ restore?: (ctx: RestoreContext) => void;
32
39
  };
33
40
 
34
41
  type Metadata = {
@@ -116,6 +123,123 @@ declare global {
116
123
  minHeimVersion?: string;
117
124
  };
118
125
 
126
+ type Inputs = Record<string, Input>;
127
+
128
+ type Input = TextInput | ConfirmInput | SelectInput | MultiselectInput;
129
+
130
+ type TextInput = {
131
+ type: "text";
132
+ /**
133
+ * The message to display to the user when prompting for input, e.g. "Enter your new username".
134
+ */
135
+ message: string;
136
+ /**
137
+ * An optional default value to pre-fill the input field, e.g. "sharknoon".
138
+ */
139
+ default?: string;
140
+ /**
141
+ * If true, the input will allow multiple lines to be entered. Default is false.
142
+ */
143
+ multiLine?: boolean;
144
+ /**
145
+ * If set, the input will be masked with this character (e.g. for passwords).
146
+ */
147
+ mask?: string;
148
+ };
149
+
150
+ type ConfirmInput = {
151
+ type: "confirm";
152
+ /**
153
+ * The message to display to the user when prompting for confirmation, e.g. "Do you want to enable feature X?".
154
+ */
155
+ message: string;
156
+ /**
157
+ * An optional default value to pre-fill the confirmation, e.g. true (which would correspond to "Yes"). Default is false.
158
+ */
159
+ default?: boolean;
160
+ /**
161
+ * The text to display for the confirmation, e.g. "Yes". Default is "Yes".
162
+ */
163
+ confirmText?: string;
164
+ /**
165
+ * The text to display for the rejection, e.g. "No". Default is "No".
166
+ */
167
+ rejectText?: string;
168
+ };
169
+
170
+ type InputOption = {
171
+ /**
172
+ * The value that is returned when the option is selected.
173
+ */
174
+ value: string;
175
+ /**
176
+ * The label that is displayed to the user.
177
+ */
178
+ label: string;
179
+ };
180
+
181
+ type SelectInput = {
182
+ type: "select";
183
+ /**
184
+ * The message to display to the user when prompting for selection, e.g. "Select your storage type".
185
+ */
186
+ message: string;
187
+ /**
188
+ * A list of options to choose from. For example: [{ value: "hdd", label: "Hard Drive" }, { value: "ssd", label: "Solid State Drive" }].
189
+ */
190
+ options: readonly InputOption[];
191
+ /**
192
+ * An optional default value to pre-select an option, e.g. "ssd". The default must match one of the values in the options array.
193
+ */
194
+ default?: string;
195
+ };
196
+
197
+ type MultiselectInput = {
198
+ type: "multiselect";
199
+ /**
200
+ * The message to display to the user when prompting for selection, e.g. "Select the video encoding backends you want to use".
201
+ */
202
+ message: string;
203
+ /**
204
+ * A list of options to choose from. For example: [{ value: "h264", label: "H.264" }, { value: "vp9", label: "VP9" }].
205
+ */
206
+ options: readonly InputOption[];
207
+ /**
208
+ * An optional list of default values to pre-select options, e.g. ["h264", "vp9"]. The defaults must match the values in the options array.
209
+ */
210
+ default?: readonly string[];
211
+ };
212
+
213
+ type InputValue<T extends Input> = T extends { type: "text" }
214
+ ? string
215
+ : T extends { type: "confirm" }
216
+ ? boolean
217
+ : T extends {
218
+ type: "select";
219
+ options: readonly {
220
+ value: infer V extends string;
221
+ label: string;
222
+ }[];
223
+ }
224
+ ? V
225
+ : T extends {
226
+ type: "multiselect";
227
+ options: readonly {
228
+ value: infer V extends string;
229
+ label: string;
230
+ }[];
231
+ }
232
+ ? V[]
233
+ : never;
234
+
235
+ type ValuesContext<I extends Inputs> = {
236
+ /**
237
+ * The resolved answers to the declared inputs. Answers are stored on installation and reused on later runs,
238
+ * so updates run unattended.
239
+ */
240
+ values: { [K in keyof I]: InputValue<I[K]> };
241
+ };
242
+
119
243
  type UserInterface = {
120
244
  /**
121
245
  * The name of the compose service that provides the user interface.
@@ -134,16 +258,25 @@ declare global {
134
258
  */
135
259
  hasAuth?: boolean;
136
260
  };
137
- type UserInterfaceContext = GlobalContext;
261
+ type UserInterfaceContext = LogContext & ConfigContext;
138
262
 
139
263
  type Compose = ComposeSpecification;
140
- type ComposeContext = GlobalContext;
264
+ type ComposeContext<I extends Inputs = Record<string, never>> = LogContext &
265
+ DataContext &
266
+ ConfigContext &
267
+ SystemContext &
268
+ ValuesContext<I> &
269
+ CryptoContext;
141
270
 
142
271
  type Backup = {
143
272
  /**
144
273
  * The volumes configuration defines which volumes of the app should be included or excluded in the backup. Each entry in the
145
- * include or exclude list can be a volume name (string) to include or exclude the entire volume, or an object with a volume
146
- * name and file filters to include or exclude only specific files within that volume. If neither the include nor the exclude
274
+ * include list can be a volume name (string) to include the entire volume, or an object with a volume
275
+ * name and file filters to include or exclude only specific files within that volume.
276
+ *
277
+ * Only whole volumes can be excluded, not specific files within a volume. To exclude specific files, use the include list with file filters.
278
+ *
279
+ * If neither the include nor the exclude
147
280
  * list is set, all volumes will be included in the backup. If both lists are set, only the volumes in the include list that
148
281
  * are not in the exclude list will be included in the backup.
149
282
  */
@@ -156,19 +289,18 @@ declare global {
156
289
  */
157
290
  include?: (string | VolumeFilter)[];
158
291
  /**
159
- * A list of volumes to exclude from the backup. Each entry can be a volume name (string) to exclude the entire volume,
160
- * or an object with a volume name and file filters to exclude only specific files within that volume.
292
+ * A list of volumes to exclude from the backup. Each entry is a volume name (string) to exclude the entire volume.
161
293
  * If neither this list nor the include list is set, all volumes will be included.
162
294
  * If both lists are set, only the volumes in the include list that are not in the exclude list will be included.
163
295
  */
164
- exclude?: (string | VolumeFilter)[];
296
+ exclude?: string[];
165
297
  };
166
298
  /**
167
- * Additional files to include in the backup that are not part of any volume. The key is the name of the artifact and the value
168
- * is the path to the file or directory to include in the backup.
169
- * The key is used to identify the artifact in the backup and can be used in the restore process to get the artifact.
299
+ * Additional data to include in the backup that is not part of any volume, such as database dumps.
300
+ * The key is the name of the artifact and the value is its content, either as text or as raw bytes.
301
+ * The name can be used in the restore process to get the artifact back.
170
302
  */
171
- artifacts?: Record<string, ArrayBuffer>;
303
+ artifacts?: Record<string, string | ArrayLike<number>>;
172
304
  };
173
305
  type VolumeFilter = {
174
306
  /**
@@ -180,22 +312,24 @@ declare global {
180
312
  * If neither this nor the exclude property is set, the entire volume will be included.
181
313
  * If both include and exclude are set, only the files that match the include patterns and do not match the exclude patterns will be included.
182
314
  */
183
- include?: string[];
315
+ includePatterns?: string[];
184
316
  /**
185
317
  * File path patterns (globs) to exclude within this volume.
186
318
  * If neither this nor the include property is set, the entire volume will be included.
187
319
  * If both include and exclude are set, only the files that match the include patterns and do not match the exclude patterns will be included.
188
320
  */
189
- exclude?: string[];
321
+ excludePatterns?: string[];
190
322
  };
191
- type BackupContext = GlobalContext & AppContext;
323
+ type BackupContext = LogContext & ConfigContext & ContainerContext;
192
324
 
193
- type Restore = {};
194
- type RestoreContext = GlobalContext & AppContext;
325
+ type RestoreContext = LogContext &
326
+ ConfigContext &
327
+ ContainerContext &
328
+ ArtifactsContext;
195
329
 
196
330
  // General types
197
331
 
198
- type GlobalContext = {
332
+ type LogContext = {
199
333
  log: {
200
334
  /**
201
335
  * Logs an informational message to the user.
@@ -210,20 +344,38 @@ declare global {
210
344
  */
211
345
  error: (message: string) => void;
212
346
  };
347
+ };
213
348
 
349
+ type DataContext = {
214
350
  data: {
215
351
  /**
216
352
  * Returns the path to a directory that can be used for shared storage between apps.
217
353
  */
218
354
  sharedStorageDir(): string;
219
355
  };
356
+ };
220
357
 
358
+ type ReadOnlyConfigContext = {
221
359
  config: {
222
360
  /**
223
361
  * Returns a previously stored configuration value for the given key. If the key does not exist, it returns null.
224
362
  * @param key The key of the configuration item to retrieve.
225
363
  */
226
364
  getItem(key: string): string | null;
365
+ /**
366
+ * Returns the number of configuration items stored.
367
+ */
368
+ size(): number;
369
+ /**
370
+ * Returns the key of the configuration item at the given index. If the index is out of bounds, it returns null.
371
+ * @param index The index of the configuration item.
372
+ */
373
+ key(index: number): string | null;
374
+ };
375
+ };
376
+
377
+ type WriteOnlyConfigContext = {
378
+ config: {
227
379
  /**
228
380
  * Stores a configuration value for the given key.
229
381
  * @param key The key of the configuration item to store.
@@ -235,21 +387,16 @@ declare global {
235
387
  * @param key The key of the configuration item to remove.
236
388
  */
237
389
  removeItem(key: string): void;
238
- /**
239
- * Returns the number of configuration items stored.
240
- */
241
- size(): number;
242
- /**
243
- * Returns the key of the configuration item at the given index. If the index is out of bounds, it returns null.
244
- * @param index The index of the configuration item.
245
- */
246
- key(index: number): string | null;
247
390
  /**
248
391
  * Removes all configuration items for this app.
249
392
  */
250
393
  clear(): void;
251
394
  };
395
+ };
396
+
397
+ type ConfigContext = ReadOnlyConfigContext & WriteOnlyConfigContext;
252
398
 
399
+ type SystemContext = {
253
400
  system: {
254
401
  /**
255
402
  * Returns a list of common IANA timezones, e.g. ["Europe/Berlin", "America/New_York", ...].
@@ -262,99 +409,9 @@ declare global {
262
409
  */
263
410
  timezone(): string;
264
411
  };
412
+ };
265
413
 
266
- input: {
267
- /**
268
- * If the id is unknown, it prompts the user for input and returns the entered value.
269
- * If the id is known, it returns the previously entered value without prompting the user.
270
- * @param id A unique id to store the input value, e.g. "db-username"
271
- * @param opts Options for the input prompt
272
- */
273
- text(opts: {
274
- /**
275
- * The message to display to the user when prompting for input, e.g. "Enter your database username".
276
- */
277
- message: string;
278
- /**
279
- * An optional default value to pre-fill the input field, e.g. "admin".
280
- */
281
- defaultValue?: string;
282
- /**
283
- * If true, the input will allow multiple lines to be entered. Default is false.
284
- */
285
- multiLine?: boolean;
286
- /**
287
- * If true, the input will be masked (e.g. for passwords). Default is false.
288
- */
289
- mask?: string;
290
- validate?: (value: string | undefined) => string | undefined;
291
- }): string;
292
- /**
293
- * If the id is unknown, it prompts the user for confirmation and returns the user's choice as a boolean.
294
- * If the id is known, it returns the previously entered value without prompting the user.
295
- * @param id A unique id to store the confirmation value, e.g. "ebnable-feature-x"
296
- * @param opts Options for the confirmation prompt
297
- */
298
- confirm(opts: {
299
- /**
300
- * The message to display to the user when prompting for confirmation, e.g. "Do you want to enable feature X?".
301
- */
302
- message: string;
303
- /**
304
- * An optional default value to pre-fill the confirmation, e.g. true (which would correspond to "Yes"). Default is false.
305
- */
306
- defaultValue?: boolean;
307
- /**
308
- * The text to display for the confirmation, e.g. "Yes". Default is "Yes".
309
- */
310
- confirmText?: string;
311
- /**
312
- * The text to display for the rejection, e.g. "No". Default is "No".
313
- */
314
- rejectText?: string;
315
- }): boolean;
316
- /**
317
- * If the id is unknown, it prompts the user to select one option from a list and returns the selected value.
318
- * If the id is known, it returns the previously selected value without prompting the user.
319
- * @param id A unique id to store the selected value, e.g. "storage-type"
320
- * @param opts Options for the select prompt
321
- */
322
- select<V extends string>(opts: {
323
- /**
324
- * The message to display to the user when prompting for selection, e.g. "Select your storage type".
325
- */
326
- message: string;
327
- /**
328
- * A list of options to choose from, where each option has a value (which is returned when the option is selected) and a label (which is displayed to the user). For example: [{ value: "hdd", label: "Hard Drive" }, { value: "ssd", label: "Solid State Drive" }].
329
- */
330
- options: { value: V; label: string }[];
331
- /**
332
- * An optional default value to pre-select an option, e.g. "ssd". The defaultValue must match one of the values in the options array.
333
- */
334
- defaultValue?: V;
335
- }): V;
336
- /**
337
- * If the id is unknown, it prompts the user to select zero, one or more options from a list and returns the selected values as an array.
338
- * If the id is known, it returns the previously selected values without prompting the user.
339
- * @param id A unique id to store the selected values, e.g. "feature-flags". The selected values are stored under the provided id and can be edited by the user later.
340
- * @param opts Options for the multiselect prompt
341
- */
342
- multiselect<V extends string>(opts: {
343
- /**
344
- * The message to display to the user when prompting for selection, e.g. "Select the video encoding backends you want to use".
345
- */
346
- message: string;
347
- /**
348
- * A list of options to choose from, where each option has a value (which is returned when the option is selected) and a label (which is displayed to the user). For example: [{ value: "h264", label: "H.264" }, { value: "vp9", label: "VP9" }, { value: "av1", label: "AV1" }].
349
- */
350
- options: { value: V; label: string }[];
351
- /**
352
- * An optional list of default values to pre-select options, e.g. ["h264", "vp9"]. The defaultValues must match the values in the options array.
353
- */
354
- defaultValues?: V[];
355
- }): V[];
356
- };
357
-
414
+ type CryptoContext = {
358
415
  crypto: {
359
416
  /**
360
417
  * Generates a random password with the specified options.
@@ -377,18 +434,76 @@ declare global {
377
434
  };
378
435
  };
379
436
 
380
- type AppContext = {
437
+ type ContainerContext = {
438
+ container: {
439
+ /**
440
+ * Executes a command in the container of a specific service. Uses docker compose exec under the hood.
441
+ *
442
+ * The output is decoded as UTF-8 text by default. Set the binary option to true
443
+ * to get the raw bytes instead, for example for binary database dumps.
444
+ *
445
+ * A non-zero exit code is reported in the result, not thrown as an error.
446
+ * An error is only thrown if the command could not be executed at all,
447
+ * for example when no running container exists for the service.
448
+ */
449
+ exec: {
450
+ (
451
+ service: string,
452
+ command: string[],
453
+ options?: ExecOptions & { binary?: false },
454
+ ): ExecResult<string>;
455
+ (
456
+ service: string,
457
+ command: string[],
458
+ options: ExecOptions & { binary: true },
459
+ ): ExecResult<ArrayLike<number>>;
460
+ };
461
+ };
462
+ };
463
+
464
+ type ExecOptions = {
381
465
  /**
382
- * A key-value store that holds all the configuration values for the app, including user input values and values set by the app itself.
466
+ * Data that is written to the standard input of the command.
383
467
  */
384
- config: Map<string, string>;
468
+ stdin?: string | ArrayLike<number>;
385
469
  /**
386
- * Executes a command in the container of a specific service. Uses docker compose exec under the hood.
470
+ * Return the output as raw bytes instead of UTF-8 text. Default is false.
387
471
  */
388
- exec: (service: string, command: string | string[]) => void;
472
+ binary?: boolean;
473
+ };
474
+
475
+ type ExecResult<T = string> = {
389
476
  /**
390
- * A key-value store that holds all the artifacts generated by the app, such as backup files, logs, and other data.
477
+ * The standard output of the command.
391
478
  */
392
- artifacts: Map<string, ArrayBuffer>;
479
+ stdout: T;
480
+ /**
481
+ * The standard error of the command.
482
+ */
483
+ stderr: T;
484
+ /**
485
+ * The standard output and standard error combined, in the order they were written.
486
+ */
487
+ output: T;
488
+ /**
489
+ * The exit code of the command. 0 means success.
490
+ */
491
+ exitCode: number;
492
+ };
493
+
494
+ type ArtifactsContext = {
495
+ /**
496
+ * The artifacts that were created e.g. by the backup, such as database dumps.
497
+ */
498
+ artifacts: {
499
+ /**
500
+ * Returns the artifact decoded as UTF-8 text, or null if it does not exist.
501
+ */
502
+ get: (name: string) => string | null;
503
+ /**
504
+ * Returns the raw bytes of the artifact, or null if it does not exist.
505
+ */
506
+ getBytes: (name: string) => ArrayLike<number> | null;
507
+ };
393
508
  };
394
509
  }