notifkit 0.1.11 → 0.1.13

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.
@@ -0,0 +1,43 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Apply notifkit's database migrations.
4
+ *
5
+ * Reads DATABASE_URL and DB_SCHEMA (from the environment or .env) and runs the
6
+ * same migrations NotifkitServer runs on start-up with autoMigrate, into the
7
+ * same schema. Safe to run repeatedly: already-applied migrations are skipped.
8
+ * Exits non-zero if anything fails.
9
+ *
10
+ * Usage:
11
+ * DATABASE_URL=postgres://user:pass@host:5432/db npx notifkit-migrate
12
+ * DATABASE_URL=... DB_SCHEMA=notifications npx notifkit-migrate
13
+ * node scripts/migrate.mjs
14
+ */
15
+
16
+ import { config } from "dotenv";
17
+ import { resolve } from "node:path";
18
+
19
+ config({ path: resolve(process.cwd(), ".env") });
20
+
21
+ if (!process.env.DATABASE_URL) {
22
+ console.error("Usage: DATABASE_URL=postgres://... [DB_SCHEMA=schema] npx notifkit-migrate");
23
+ process.exit(1);
24
+ }
25
+
26
+ try {
27
+ // Imported after .env is loaded: the package reads DB_SCHEMA from the environment.
28
+ const { migrateDatabase } = await import("../dist/index.mjs");
29
+ const schema = await migrateDatabase({ url: process.env.DATABASE_URL });
30
+ console.log(`Migrations applied to schema "${schema}".`);
31
+ } catch (err) {
32
+ console.error(`Failed to run migrations: ${describe(err)}`);
33
+ process.exitCode = 1;
34
+ }
35
+
36
+ /** drizzle wraps driver errors as "Failed query: ..."; the cause says what actually went wrong. */
37
+ function describe(err) {
38
+ const parts = [err.message];
39
+ if (err.fields) parts.push(JSON.stringify(err.fields));
40
+ const cause = err.cause;
41
+ if (cause) parts.push(`cause: ${cause.message || cause.code || String(cause)}`);
42
+ return parts.join("\n ");
43
+ }
@@ -0,0 +1,42 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * The `notifkit` command. Today it has one subcommand, which hands off to
4
+ * create-notifkit so both spellings scaffold the same app:
5
+ *
6
+ * npx notifkit create my-app
7
+ * npm create notifkit@latest my-app
8
+ */
9
+
10
+ import { spawn } from "node:child_process";
11
+
12
+ const [command, ...args] = process.argv.slice(2);
13
+
14
+ if (command !== "create") {
15
+ console.error(
16
+ "Usage: notifkit create [name] [options]\n\n" +
17
+ "Scaffolds a new notifkit app. Run `notifkit create --help` for options.",
18
+ );
19
+ process.exit(command ? 1 : 0);
20
+ }
21
+
22
+ const npmArgs = [
23
+ "exec",
24
+ "--yes",
25
+ "--package=create-notifkit@latest",
26
+ "--",
27
+ "create-notifkit",
28
+ ...args,
29
+ ];
30
+
31
+ // npm is a .cmd shim on Windows, which only runs through a shell.
32
+ const quote = (a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a);
33
+ const child =
34
+ process.platform === "win32"
35
+ ? spawn(["npm", ...npmArgs].map(quote).join(" "), { stdio: "inherit", shell: true })
36
+ : spawn("npm", npmArgs, { stdio: "inherit" });
37
+
38
+ child.on("error", (err) => {
39
+ console.error(`notifkit create: could not run npm (${err.message})`);
40
+ process.exit(1);
41
+ });
42
+ child.on("exit", (code) => process.exit(code ?? 1));
@@ -69,6 +69,17 @@ export const baseConfigSchema = z.object({
69
69
  */
70
70
  IDEMPOTENCY_TTL_SECONDS: z.coerce.number().int().min(60).default(3600),
71
71
  DB_MAX_CONNECTIONS: z.coerce.number().int().min(1).default(2),
72
+ /**
73
+ * PostgreSQL schema that holds notifkit's tables and enum types. Defaults to
74
+ * `public`. Any other value makes migrations create every object in that
75
+ * schema and sets `search_path` on every connection, so notifkit can share a
76
+ * database with an application that owns `public`.
77
+ */
78
+ DB_SCHEMA: z
79
+ .string()
80
+ .trim()
81
+ .regex(/^[a-z_][a-z0-9_]{0,62}$/, "must be a lowercase PostgreSQL identifier")
82
+ .default("public"),
72
83
  LOG_FLUSH_INTERVAL_MS: z.coerce.number().int().min(50).default(500),
73
84
  LOG_BUFFER_MAX_SIZE: z.coerce.number().int().min(100).default(5000),
74
85
  SEGMENT_MAX_USERS: z.coerce.number().int().min(1).default(10000),
package/src/db/index.ts CHANGED
@@ -9,6 +9,11 @@ export type Db = PostgresJsDatabase<typeof schema>;
9
9
 
10
10
  export interface DatabaseOptions {
11
11
  url: string;
12
+ /**
13
+ * Schema holding notifkit's tables. Defaults to `DB_SCHEMA` (`public`).
14
+ * Anything else is set as the connection's `search_path`.
15
+ */
16
+ schema?: string;
12
17
  applicationName?: string;
13
18
  maxConnections?: number;
14
19
  idleTimeoutSeconds?: number;
@@ -27,12 +32,14 @@ export interface DatabaseClients {
27
32
  */
28
33
  export function createDatabase({
29
34
  url,
35
+ schema: dbSchema,
30
36
  applicationName = "notifkit",
31
37
  maxConnections,
32
38
  idleTimeoutSeconds = 30,
33
39
  logger,
34
40
  }: DatabaseOptions): DatabaseClients {
35
41
  const finalMaxConnections = maxConnections ?? readBaseConfig().DB_MAX_CONNECTIONS;
42
+ const finalSchema = resolveSchema(dbSchema);
36
43
 
37
44
  const sql = postgres(url, {
38
45
  max: finalMaxConnections,
@@ -40,6 +47,9 @@ export function createDatabase({
40
47
  connection: {
41
48
  application_name: applicationName,
42
49
  statement_timeout: 10000 as any, // prevent TS issues with postgres.js types
50
+ // Unqualified queries resolve against this schema only, so a same-named
51
+ // table in `public` can never be picked up by mistake.
52
+ ...(finalSchema === DEFAULT_SCHEMA ? {} : { search_path: quoteIdentifier(finalSchema) }),
43
53
  },
44
54
  onnotice: (notice) => {
45
55
  logger?.debug({ notice }, "postgres notice");
@@ -52,18 +62,175 @@ export function createDatabase({
52
62
  }
53
63
 
54
64
  import { migrate } from "drizzle-orm/postgres-js/migrator";
65
+ import { getTableName, is, sql as drizzleSql } from "drizzle-orm";
66
+ import { PgTable } from "drizzle-orm/pg-core";
55
67
  import { fileURLToPath } from "url";
68
+ import os from "os";
56
69
  import path from "path";
57
70
  import fs from "fs";
58
71
 
59
- export async function runMigrations(db: Db) {
72
+ const DEFAULT_SCHEMA = "public";
73
+ const SCHEMA_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
74
+ const STATEMENT_BREAKPOINT = "--> statement-breakpoint";
75
+
76
+ export interface MigrationOptions {
77
+ /** Schema to create notifkit's objects in. Defaults to `DB_SCHEMA` (`public`). */
78
+ schema?: string;
79
+ /**
80
+ * Schema of drizzle's migration journal table. Defaults to drizzle's own
81
+ * `drizzle` for `public`, and to `schema` otherwise, so two installs in
82
+ * different schemas of one database never share a journal.
83
+ */
84
+ migrationsSchema?: string;
85
+ /** Name of drizzle's migration journal table. Defaults to `__drizzle_migrations`. */
86
+ migrationsTable?: string;
87
+ }
88
+
89
+ function resolveSchema(schema?: string): string {
90
+ const name = schema ?? readBaseConfig().DB_SCHEMA;
91
+ if (!SCHEMA_NAME.test(name)) {
92
+ throw new Error(`Invalid database schema "${name}": must be a lowercase PostgreSQL identifier`);
93
+ }
94
+ return name;
95
+ }
96
+
97
+ function quoteIdentifier(name: string): string {
98
+ return `"${name}"`;
99
+ }
100
+
101
+ function packagedMigrationsFolder(): string {
60
102
  const __filename = fileURLToPath(import.meta.url);
61
103
  const __dirname = path.dirname(__filename);
62
104
 
63
- let migrationsFolder = path.resolve(__dirname, "../../drizzle");
64
- if (!fs.existsSync(migrationsFolder)) {
65
- migrationsFolder = path.resolve(__dirname, "../drizzle");
105
+ const folder = path.resolve(__dirname, "../../drizzle");
106
+ return fs.existsSync(folder) ? folder : path.resolve(__dirname, "../drizzle");
107
+ }
108
+
109
+ /**
110
+ * Retarget one generated migration at `schema`. drizzle-kit qualifies enum
111
+ * types and foreign-key targets with `"public".` but leaves tables and indexes
112
+ * unqualified, so both halves have to move: the qualifier is rewritten, and
113
+ * `SET LOCAL search_path` places the unqualified objects. `SET LOCAL` ends with
114
+ * the migration transaction and never leaks into a pooled connection.
115
+ *
116
+ * Throws if `public` is still mentioned after the rewrite: a migration that
117
+ * spells the schema some other way would otherwise put objects into `public`
118
+ * without a word.
119
+ */
120
+ export function qualifyMigrationSql(source: string, schema: string): string {
121
+ const rewritten = source.replaceAll(`"${DEFAULT_SCHEMA}".`, `${quoteIdentifier(schema)}.`);
122
+ if (/\bpublic\b/i.test(rewritten)) {
123
+ throw new Error(
124
+ `Migration still references the public schema after retargeting it to "${schema}"`,
125
+ );
126
+ }
127
+ return `SET LOCAL search_path TO ${quoteIdentifier(schema)};\n${STATEMENT_BREAKPOINT}\n${rewritten}`;
128
+ }
129
+
130
+ /** Copy the journal and every migration it lists into `target`, retargeted at `schema`. */
131
+ function writeSchemaMigrations(source: string, target: string, schema: string): void {
132
+ const journalPath = path.join(source, "meta", "_journal.json");
133
+ const journal = JSON.parse(fs.readFileSync(journalPath, "utf8")) as {
134
+ entries: { tag: string }[];
135
+ };
136
+
137
+ fs.mkdirSync(path.join(target, "meta"));
138
+ fs.copyFileSync(journalPath, path.join(target, "meta", "_journal.json"));
139
+ for (const { tag } of journal.entries) {
140
+ const file = `${tag}.sql`;
141
+ const migration = fs.readFileSync(path.join(source, file), "utf8");
142
+ fs.writeFileSync(path.join(target, file), qualifyMigrationSql(migration, schema));
143
+ }
144
+ }
145
+
146
+ export async function runMigrations(db: Db, options: MigrationOptions = {}) {
147
+ const migrationsFolder = packagedMigrationsFolder();
148
+ const schema = resolveSchema(options.schema);
149
+ const { migrationsTable } = options;
150
+
151
+ if (schema === DEFAULT_SCHEMA) {
152
+ await migrate(db, {
153
+ migrationsFolder,
154
+ migrationsTable,
155
+ migrationsSchema: options.migrationsSchema,
156
+ });
157
+ return;
66
158
  }
67
159
 
68
- await migrate(db, { migrationsFolder });
160
+ await db.execute(drizzleSql`CREATE SCHEMA IF NOT EXISTS ${drizzleSql.identifier(schema)}`);
161
+
162
+ const retargeted = fs.mkdtempSync(path.join(os.tmpdir(), "notifkit-migrations-"));
163
+ try {
164
+ writeSchemaMigrations(migrationsFolder, retargeted, schema);
165
+ await migrate(db, {
166
+ migrationsFolder: retargeted,
167
+ migrationsTable,
168
+ migrationsSchema: options.migrationsSchema ?? schema,
169
+ });
170
+ } finally {
171
+ fs.rmSync(retargeted, { recursive: true, force: true });
172
+ }
173
+
174
+ await assertTablesInSchema(db, schema);
175
+ }
176
+
177
+ /**
178
+ * Names of every table notifkit's Drizzle schema defines, sorted. This is the
179
+ * same object the ORM queries at run time, so the list cannot drift from the
180
+ * tables notifkit actually uses.
181
+ */
182
+ export function notifkitTableNames(): string[] {
183
+ return Object.values(schema as Record<string, unknown>)
184
+ .filter((value): value is PgTable => is(value, PgTable))
185
+ .map((table) => getTableName(table))
186
+ .sort();
187
+ }
188
+
189
+ /**
190
+ * Fail if any notifkit table is missing from `targetSchema`. Run after
191
+ * migrating into a custom schema: if the retargeting ever stops working (the
192
+ * `search_path` is overridden, a migration is skipped because of a shared
193
+ * journal, ...), the tables land elsewhere or nowhere, and every runtime query
194
+ * would fail with "relation does not exist". Only the target schema is checked:
195
+ * the application sharing the database may well own `users` or `projects` in
196
+ * `public`, and that is not an error.
197
+ */
198
+ export async function assertTablesInSchema(db: Db, targetSchema: string): Promise<void> {
199
+ const rows = await db.execute<{ table_name: string }>(
200
+ drizzleSql`SELECT table_name FROM information_schema.tables WHERE table_schema = ${targetSchema}`,
201
+ );
202
+ const present = new Set(rows.map((row) => row.table_name));
203
+ const missing = notifkitTableNames().filter((name) => !present.has(name));
204
+ if (missing.length > 0) {
205
+ throw new Error(
206
+ `Migrations finished, but schema "${targetSchema}" is missing notifkit tables: ${missing.join(", ")}`,
207
+ );
208
+ }
209
+ }
210
+
211
+ /**
212
+ * Apply the bundled migrations to the database at `url` and close the
213
+ * connection, whether or not they succeed. `schema` defaults to `DB_SCHEMA`.
214
+ * This is what `notifkit-migrate` runs.
215
+ */
216
+ export async function migrateDatabase({
217
+ url,
218
+ schema: dbSchema,
219
+ }: {
220
+ url: string;
221
+ schema?: string;
222
+ }): Promise<string> {
223
+ const targetSchema = resolveSchema(dbSchema);
224
+ const { db, sql } = createDatabase({
225
+ url,
226
+ schema: targetSchema,
227
+ applicationName: "notifkit-migrate",
228
+ maxConnections: 1,
229
+ });
230
+ try {
231
+ await runMigrations(db, { schema: targetSchema });
232
+ } finally {
233
+ await sql.end();
234
+ }
235
+ return targetSchema;
69
236
  }
package/src/server.ts CHANGED
@@ -41,6 +41,8 @@ export interface NotifkitOptions {
41
41
  };
42
42
  dbOptions?: {
43
43
  maxConnections?: number;
44
+ /** PostgreSQL schema for notifkit's tables. Same as `DB_SCHEMA`; defaults to `public`. */
45
+ schema?: string;
44
46
  };
45
47
  }
46
48
 
@@ -102,6 +104,7 @@ export class NotifkitServer extends EventEmitter {
102
104
  process.env.QUEUE_MAX_LEN = String(this.options.redisOptions.maxQueueLength);
103
105
  if (this.options.dbOptions?.maxConnections)
104
106
  process.env.DB_MAX_CONNECTIONS = String(this.options.dbOptions.maxConnections);
107
+ if (this.options.dbOptions?.schema) process.env.DB_SCHEMA = this.options.dbOptions.schema;
105
108
 
106
109
  const isProduction = process.env.NODE_ENV === "production";
107
110