Mirror of https://github.com/roostorg/coop
github.com/roostorg/coop
1import {
2 type MigrationParams,
3 type RunnableMigration,
4 type UmzugStorage,
5} from 'umzug';
6
7export type Bind1<
8 F extends (arg0: A0, ...args: never[]) => unknown,
9 A0,
10> = F extends (arg0: A0, ...args: infer Args) => infer R
11 ? (...args: Args) => R
12 : never;
13
14/**
15 * Every database for which we want to support migrations must provide a config
16 * object for itself that satisfies this type.
17 *
18 * NB: file extensions in the options below should be given with no leading dot.
19 *
20 * NB: "scripts" refers collectively to migrations or seed files.
21 */
22export type DatabaseConfig<
23 SupportedScriptFormat extends string = string,
24 ContextType = unknown,
25 StorageType extends UmzugStorage = UmzugStorage,
26> = {
27 /**
28 * The file type (i.e., extension) to use for a new script when a file type
29 * isn't specified explicitly.
30 */
31 readonly defaultScriptFormat: SupportedScriptFormat;
32
33 /**
34 * A list of supported file extensions for this db's scripts (no leading dot).
35 */
36 readonly supportedScriptFormats: readonly SupportedScriptFormat[];
37
38 /**
39 * The directory in which the migrator will look for this db's scripts and
40 * into which it'll create new scripts.
41 */
42 readonly scriptsDirectory: string;
43
44 /**
45 * Which environments does this db support?
46 */
47 readonly supportedEnvironments: readonly string[];
48
49 /**
50 * A reference to the database client/connection that is passed to the Umzug
51 * storage object. Used in the case of a custom UmzugStorage implementation
52 * to ensure we close all connections to the database.
53 */
54 storageDbClient?: unknown;
55
56 /**
57 * Creates this db to with an initial state and then closes any open
58 * connections/resources.
59 */
60 prepareDbAndDisconnect(): Promise<void>;
61
62 /**
63 * Deletes this db and then closes any open connections/resources.
64 */
65 dropDbAndDisconnect(): Promise<void>;
66
67 /**
68 * Returns an object capable of recording that a script has been run, listing
69 * the scripts that have run, and removing the record of a script (if it's
70 * rolled back).
71 */
72 createStorage(): UmzugStorage<ContextType>;
73
74 /**
75 * Takes the name and path of a script and turns it into a runnable object
76 * that has an `up` and (optionally) `down` method. `up` and `down` will be
77 * called with the context object (see below) and should actually update the
78 * database.
79 */
80 resolveScript(
81 params: MigrationParams<ContextType> & { path: string },
82 ): RunnableMigration<ContextType>;
83
84 /**
85 * Returns a "context" object, which is simply an object that'll be passed to
86 * all scripts. Often this context object is an instance of the db driver
87 * connected to the database.
88 */
89 createContext(): ContextType | Promise<ContextType>;
90
91 /**
92 * A function that destroys the context object and cleans up associated
93 * resources. This is called after all the migrations have been run with the
94 * context. If the context has an open db connection, that connection should
95 * be closed so the process can exit.
96 */
97 destroyContext(context: ContextType): Promise<void>;
98
99 /**
100 * A function that destroys the storage object and cleans up associated
101 * resources. This is called after all the migrations have been run with the
102 * storage. If the storage has an open db connection, that connection should
103 * be closed so the process can exit.
104 */
105 destroyStorage?(context: StorageType): Promise<void>;
106
107 /**
108 * Given the path of the new script file that is being created, returns a
109 * string that will be that file's initial contents. This template can include
110 * helper/boilerplate code, like common imports.
111 */
112 getTemplate?(filePath: string): string;
113};