@meghjs/cli 0.6.0 → 0.6.1

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.
@@ -1,19 +1,3 @@
1
- ### ⚠️ WARNING: NOT FOR PRODUCTION USE
2
-
3
- > **🚧 This project is in active development.**
4
- >
5
- > It is **not stable** and **not ready** for live environments.
6
- > Use **only for testing, experimentation, or internal evaluation**.
7
- >
8
- > #### ❗ Risks of using this in production:
9
- >
10
- > - 🔄 Breaking changes may be introduced at any time
11
- > - 🧪 Features are experimental and may be unstable
12
- > - 🔐 Security has not been audited
13
- > - 💥 Potential for data loss or critical errors
14
- >
15
- > **Please do not deploy this in production environments.**
16
-
17
1
  # Megh CLI
18
2
 
19
3
  Scaffold and run [Megh](https://github.com/meghjs/megh) applications.
@@ -25,7 +9,7 @@ npx @meghjs/cli new my_api
25
9
  ```
26
10
 
27
11
  You are prompted for a package manager and for optional features (OpenAPI,
28
- CORS, TypeORM, Knex, Scalar UI). The generated project uses `@meghjs/core`'s
12
+ CORS, MeghORM, TypeORM, Knex, Scalar UI, Mail). The generated project uses `@meghjs/core`'s
29
13
  `Megh.createApplication()` and is ready to run:
30
14
 
31
15
  ```sh
@@ -37,7 +21,7 @@ npm run start:dev
37
21
 
38
22
  | Command | Alias | Options | Description |
39
23
  |---------|-------|---------|-------------|
40
- | `new <name>` | | `-m`, `-f`, `-y`, `--pm <npm\|yarn\|pnpm>`, `--features <list>`, `--skip-install` | Create a new application |
24
+ | `new <name>` | | `-m`, `-f`, `-y`, `--pm <npm\|yarn\|pnpm>`, `--features <list>`, `--skip-install`, `--skip-git` | Create a new application |
41
25
  | `serve` | | `--entry <file>`, `--no-type-check`, `--debounce <ms>` | Dev server: SWC compile, run, reload on change |
42
26
  | `build` | | `-p <tsconfig>` | Compile with `tsconfig.build.json` and copy assets |
43
27
  | `start` | | `--entry <file>` | Run the compiled app with `NODE_ENV=production` |
@@ -51,6 +35,7 @@ npm run start:dev
51
35
  | `make:config` | `m:cnf` | `-f`, `--root <dir>` | Create an `@AppConfig` class |
52
36
  | `make:middleware` | `m:mlwr` | `-f`, `--root <dir>` | Create a middleware |
53
37
  | `make:dto` | `m:dto` | `-f`, `--root <dir>` | Create a class-validator DTO |
38
+ | `make:mail` | `m:mail` | `-f`, `--root <dir>` | Create a Mailable in `src/mail` |
54
39
  | `make:seeder` | `m:sd` | `-f` | Create a seeder in `src/database/seeders` (`database` for the entry seeder) |
55
40
  | `db:seed` | | `-s <name>`, `--force` | Run the seeders in one transaction (also `migrate --seed`) |
56
41
  | `make:factory` | `m:f` | `-f` | Create a model factory in `src/database/factories`, with Faker values per column |
@@ -115,6 +100,18 @@ npx megh make:middleware auth
115
100
 
116
101
  Generates a class extending `MeghMiddleware` with an `invoke(req, res)` method.
117
102
 
103
+ ### Mail
104
+
105
+ ```sh
106
+ npx megh make:mail OrderShipped
107
+ ```
108
+
109
+ Generates `src/mail/order-shipped.mail.ts`, an `OrderShippedMail` class
110
+ extending `Mailable` with `envelope()`, `content()` and `attachments()`. Send it
111
+ with the injected `Mailer`: `mailer.to(user.email).send(new OrderShippedMail())`.
112
+ Mail must be turned on in `src/app.ts` with `app.useMail()`; projects created
113
+ with the `mail` feature already have it.
114
+
118
115
  ### Config
119
116
 
120
117
  ```sh
@@ -1,6 +1,6 @@
1
1
  export declare const PACKAGE_MANAGERS: readonly ["npm", "yarn", "pnpm"];
2
2
  export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
3
- export declare const FEATURES: readonly ["openapi", "cors", "orm", "typeorm", "knex", "scalar"];
3
+ export declare const FEATURES: readonly ["openapi", "cors", "orm", "typeorm", "knex", "scalar", "mail"];
4
4
  export type Feature = (typeof FEATURES)[number];
5
5
  /** Databases MeghORM (the `orm` feature) can connect to. */
6
6
  export declare const DATABASES: readonly ["postgres", "mysql", "sqlite", "mssql"];
@@ -17,8 +17,17 @@ export type NewOptions = {
17
17
  database?: string;
18
18
  /** Skip `<pm> install`. Also enabled by the `MEGH_SKIP_INSTALL=1` environment variable. */
19
19
  skipInstall?: boolean;
20
+ /** Skip `git init`. Also enabled by the `MEGH_SKIP_GIT=1` environment variable. */
21
+ skipGit?: boolean;
20
22
  };
21
23
  export declare function packageJson(name: string, features: Feature[], minimal: boolean, database?: DatabaseKind): string;
22
24
  export declare function installCommand(pm: PackageManager): string;
23
25
  export declare function devCommand(pm: PackageManager): string;
26
+ type GitResult = "initialized" | "no-git" | "inside-repo" | "failed";
27
+ /**
28
+ * Run `git init` in a new project. Skipped when git is not installed, or when
29
+ * the folder is already inside a repository (e.g. `megh new .` in a repo).
30
+ */
31
+ export declare function initGit(cwd: string): GitResult;
24
32
  export declare function createApplication(name: string, opts?: NewOptions): Promise<string>;
33
+ export {};
@@ -40,6 +40,7 @@ exports.DATABASES = exports.FEATURES = exports.PACKAGE_MANAGERS = void 0;
40
40
  exports.packageJson = packageJson;
41
41
  exports.installCommand = installCommand;
42
42
  exports.devCommand = devCommand;
43
+ exports.initGit = initGit;
43
44
  exports.createApplication = createApplication;
44
45
  const child_process_1 = require("child_process");
45
46
  const fs_1 = __importDefault(require("fs"));
@@ -51,7 +52,7 @@ const make_1 = require("../generators/make");
51
52
  const stubs_1 = require("../utils/stubs");
52
53
  const env_types_1 = require("../utils/env-types");
53
54
  exports.PACKAGE_MANAGERS = ["npm", "yarn", "pnpm"];
54
- exports.FEATURES = ["openapi", "cors", "orm", "typeorm", "knex", "scalar"];
55
+ exports.FEATURES = ["openapi", "cors", "orm", "typeorm", "knex", "scalar", "mail"];
55
56
  const DEFAULT_FEATURES = ["openapi"];
56
57
  /** Databases MeghORM (the `orm` feature) can connect to. */
57
58
  exports.DATABASES = ["postgres", "mysql", "sqlite", "mssql"];
@@ -73,6 +74,8 @@ const DEP_VERSIONS = {
73
74
  "class-validator": "^0.14.2",
74
75
  "reflect-metadata": "^0.2.2",
75
76
  "@fastify/cors": "^11.0.0",
77
+ "@fastify/swagger": "^9.7.0",
78
+ "@fastify/swagger-ui": "^6.1.2",
76
79
  typeorm: "^0.3.20",
77
80
  pg: "^8.11.0",
78
81
  mysql2: "^3.11.0",
@@ -81,6 +84,7 @@ const DEP_VERSIONS = {
81
84
  tarn: "^3.0.2",
82
85
  knex: "^3.1.0",
83
86
  "@scalar/fastify-api-reference": "^1.0.0",
87
+ nodemailer: "^10.5.0",
84
88
  typescript: "^5.7.2",
85
89
  "@types/node": "^22.20.5",
86
90
  vitest: "^4.1.12",
@@ -144,6 +148,7 @@ async function prompt(opts) {
144
148
  { name: "TypeORM", value: "typeorm" },
145
149
  { name: "Knex", value: "knex" },
146
150
  { name: "Scalar UI (replaces Swagger UI)", value: "scalar" },
151
+ { name: "Mail: mailables, SMTP and API mailers, queued mail", value: "mail" },
147
152
  ],
148
153
  },
149
154
  ]));
@@ -190,8 +195,16 @@ function packageJson(name, features, minimal, database = DEFAULT_DATABASE) {
190
195
  pick("knex", "pg");
191
196
  if (features.includes("orm"))
192
197
  pick(...DATABASE_SETUP[database].drivers);
198
+ // useOpenApi() builds the spec with @fastify/swagger, then serves it with
199
+ // Swagger UI, or with Scalar when that is chosen.
200
+ if (features.includes("openapi") || features.includes("scalar"))
201
+ pick("@fastify/swagger");
193
202
  if (features.includes("scalar"))
194
203
  pick("@scalar/fastify-api-reference");
204
+ else if (features.includes("openapi"))
205
+ pick("@fastify/swagger-ui");
206
+ if (features.includes("mail"))
207
+ pick("nodemailer");
195
208
  const devDeps = {};
196
209
  const pickDev = (...names) => names.forEach((n) => (devDeps[n] = DEP_VERSIONS[n]));
197
210
  pickDev("@types/node", "typescript");
@@ -247,6 +260,9 @@ function appSource(features) {
247
260
  if (features.includes("orm")) {
248
261
  setup.push(`// Connects from DATABASE_URL in .env; megh migrate uses the same setting.\napp.useMeghORM();`);
249
262
  }
263
+ if (features.includes("mail")) {
264
+ setup.push(`// Settings come from MEGH_MAIL_* in .env. Inject Mailer to send a Mailable.\napp.useMail();`);
265
+ }
250
266
  if (features.includes("typeorm")) {
251
267
  setup.push(`// TODO: pass your TypeORM DataSourceOptions (or an @AppConfig class)\n` +
252
268
  `// await app.useTypeORM({ type: 'postgres', url: process.env.DATABASE_URL, entities: [] });`);
@@ -260,6 +276,28 @@ function appSource(features) {
260
276
  Setup: setup.map((s) => "\n" + s + "\n").join(""),
261
277
  });
262
278
  }
279
+ /**
280
+ * The mail section of `.env`. No mailer is set: in development mail is then
281
+ * written to the log, and in production the app refuses to start until one is.
282
+ */
283
+ function mailEnv(appTitle) {
284
+ return [
285
+ "",
286
+ "# Mail: app.useMail(). With no MEGH_MAIL_MAILER, mail goes to the log in",
287
+ "# development, and the app will not start in production until one is set.",
288
+ "# MEGH_MAIL_MAILER=smtp",
289
+ "# MEGH_MAIL_HOST=127.0.0.1",
290
+ "# MEGH_MAIL_PORT=1025",
291
+ "# MEGH_MAIL_USERNAME=",
292
+ "# MEGH_MAIL_PASSWORD=",
293
+ "# MEGH_MAIL_ENCRYPTION=tls",
294
+ "# Or an API mailer: sendgrid, mailgun, postmark or resend.",
295
+ "# MEGH_MAIL_SENDGRID_API_KEY=",
296
+ "MEGH_MAIL_FROM_ADDRESS=hello@example.com",
297
+ `MEGH_MAIL_FROM_NAME="${appTitle.replace(/"/g, "")}"`,
298
+ "",
299
+ ].join("\n");
300
+ }
263
301
  function installCommand(pm) {
264
302
  return `${pm} install`;
265
303
  }
@@ -268,11 +306,28 @@ function devCommand(pm) {
268
306
  }
269
307
  function runInstall(pm, cwd) {
270
308
  return new Promise((resolve, reject) => {
271
- const child = (0, child_process_1.spawn)(pm, ["install"], { cwd, stdio: "inherit", shell: process.platform === "win32" });
309
+ // Windows needs a shell to run npm.cmd/yarn.cmd/pnpm.cmd. Passing one command
310
+ // string (not an args array) keeps Node 24 from warning with DEP0190.
311
+ const child = process.platform === "win32"
312
+ ? (0, child_process_1.spawn)(`${pm} install`, { cwd, stdio: "inherit", shell: true })
313
+ : (0, child_process_1.spawn)(pm, ["install"], { cwd, stdio: "inherit" });
272
314
  child.on("error", reject);
273
315
  child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`${pm} install exited with code ${code}`))));
274
316
  });
275
317
  }
318
+ /**
319
+ * Run `git init` in a new project. Skipped when git is not installed, or when
320
+ * the folder is already inside a repository (e.g. `megh new .` in a repo).
321
+ */
322
+ function initGit(cwd) {
323
+ const git = (...args) => (0, child_process_1.spawnSync)("git", args, { cwd, stdio: "ignore" });
324
+ const version = git("--version");
325
+ if (version.error || version.status !== 0)
326
+ return "no-git";
327
+ if (git("rev-parse", "--is-inside-work-tree").status === 0)
328
+ return "inside-repo";
329
+ return git("init").status === 0 ? "initialized" : "failed";
330
+ }
276
331
  async function createApplication(name, opts = {}) {
277
332
  if (!name || !name.trim())
278
333
  throw new errors_1.CliError("Please provide a project name, e.g. `megh new my-api`.");
@@ -327,6 +382,10 @@ async function createApplication(name, opts = {}) {
327
382
  add("src/database/migrations/.gitkeep", "");
328
383
  add("src/database/seeders/database.seeder.ts", (0, make_1.renderEntrySeeder)([]));
329
384
  }
385
+ if (features.includes("mail")) {
386
+ env = env.replace(/\n*$/, "\n") + mailEnv((0, names_1.titleCase)(appName) || appName);
387
+ add("src/mail/welcome.mail.ts", (0, stubs_1.renderStub)("mail/mail.stub", { ClassName: "WelcomeMail", Title: "Welcome" }));
388
+ }
330
389
  add(".gitignore", gitignore);
331
390
  add(".env", env);
332
391
  add("README.md", (0, stubs_1.renderStub)("project/readme.stub", {
@@ -346,6 +405,13 @@ async function createApplication(name, opts = {}) {
346
405
  }
347
406
  if (!minimal)
348
407
  fs_1.default.mkdirSync(path_1.default.join(root, "public"), { recursive: true });
408
+ if (!opts.skipGit && process.env.MEGH_SKIP_GIT !== "1") {
409
+ const git = initGit(root);
410
+ if (git === "initialized")
411
+ log_1.log.success("Initialized a git repository");
412
+ else if (git === "failed")
413
+ log_1.log.warn("git init failed; run it yourself to put the project under git");
414
+ }
349
415
  const skipInstall = opts.skipInstall || process.env.MEGH_SKIP_INSTALL === "1";
350
416
  if (skipInstall) {
351
417
  log_1.log.section("Skipping dependency install");
@@ -64,6 +64,8 @@ export type MakeResourceOptions = Pick<MakeBaseOptions, "cwd" | "force"> & {
64
64
  export declare function makeResource(name: string, opts?: MakeResourceOptions): string[];
65
65
  export declare function makeConfig(name: string, opts?: MakeBaseOptions): string;
66
66
  export declare function makeMiddleware(name: string, opts?: MakeBaseOptions): string;
67
+ /** A Mailable in src/mail/<name>.mail.ts: `make:mail Welcome` writes `WelcomeMail`. */
68
+ export declare function makeMail(name: string, opts?: MakeBaseOptions): string;
67
69
  export declare function makeDto(name: string, opts?: MakeBaseOptions): string;
68
70
  export type MakeMigrationOptions = Pick<MakeBaseOptions, "cwd" | "force"> & {
69
71
  /** Create this table (overrides the name-based guess). */
@@ -11,6 +11,7 @@ exports.makeController = makeController;
11
11
  exports.makeResource = makeResource;
12
12
  exports.makeConfig = makeConfig;
13
13
  exports.makeMiddleware = makeMiddleware;
14
+ exports.makeMail = makeMail;
14
15
  exports.makeDto = makeDto;
15
16
  exports.migrationTimestamp = migrationTimestamp;
16
17
  exports.makeMigration = makeMigration;
@@ -37,6 +38,7 @@ const DEFAULT_DIRS = {
37
38
  config: "config",
38
39
  middleware: "middlewares",
39
40
  dto: "dtos",
41
+ mail: "mail",
40
42
  };
41
43
  function targetDir(projectRoot, kind, dirs, root) {
42
44
  const folder = root ? root.split(/[\\/]+/).filter(Boolean) : [DEFAULT_DIRS[kind]];
@@ -372,6 +374,27 @@ function makeMiddleware(name, opts = {}) {
372
374
  const file = path_1.default.join(targetDir(projectRoot, "middleware", n.dirs, opts.root), `${n.fileBase}.middleware.ts`);
373
375
  return write(file, (0, stubs_1.renderStub)("middlewares/middleware.stub", { ClassName: n.className }), opts.force, "Middleware", projectRoot);
374
376
  }
377
+ /** A Mailable in src/mail/<name>.mail.ts: `make:mail Welcome` writes `WelcomeMail`. */
378
+ function makeMail(name, opts = {}) {
379
+ const projectRoot = (0, project_1.requireProjectRoot)(opts.cwd ?? process.cwd());
380
+ const n = (0, names_1.resolveName)(name, "Mail");
381
+ const file = path_1.default.join(targetDir(projectRoot, "mail", n.dirs, opts.root), `${n.fileBase}.mail.ts`);
382
+ const title = n.base.replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2");
383
+ write(file, (0, stubs_1.renderStub)("mail/mail.stub", { ClassName: n.className, Title: title }), opts.force, "Mail", projectRoot);
384
+ if (!usesMail(projectRoot)) {
385
+ log_1.log.info(" Turn mail on in src/app.ts with app.useMail(), and set MEGH_MAIL_* in .env.");
386
+ }
387
+ return file;
388
+ }
389
+ /** Whether src/app.ts already calls useMail(). */
390
+ function usesMail(projectRoot) {
391
+ try {
392
+ return /\.useMail\(/.test(fs_1.default.readFileSync(path_1.default.join(projectRoot, "src", "app.ts"), "utf8"));
393
+ }
394
+ catch {
395
+ return false;
396
+ }
397
+ }
375
398
  function makeDto(name, opts = {}) {
376
399
  const projectRoot = (0, project_1.requireProjectRoot)(opts.cwd ?? process.cwd());
377
400
  const n = (0, names_1.resolveName)(name, "Dto");
package/dist/program.js CHANGED
@@ -73,6 +73,7 @@ function createProgram(run = {}) {
73
73
  .option("--features <list>", `Comma-separated features: ${new_1.FEATURES.join(", ")}`, parseList)
74
74
  .option("--database <name>", `Set up MeghORM (the orm feature) for ${new_1.DATABASES.join(", ")}. Defaults to sqlite with orm`)
75
75
  .option("--skip-install", "Do not install dependencies (or set MEGH_SKIP_INSTALL=1)")
76
+ .option("--skip-git", "Do not run git init (or set MEGH_SKIP_GIT=1)")
76
77
  .action(async (name, o) => {
77
78
  await (0, new_1.createApplication)(name, { cwd: cwd(), ...o });
78
79
  });
@@ -258,6 +259,11 @@ function createProgram(run = {}) {
258
259
  .action((name, o) => {
259
260
  (0, make_1.makeMiddleware)(name, { cwd: cwd(), ...o });
260
261
  });
262
+ make("make:mail", ["m:mail"], "Create a Mailable in src/mail/<name>.mail.ts")
263
+ .option("--root <dir>", "Folder under src/ to write to (also -rt)")
264
+ .action((name, o) => {
265
+ (0, make_1.makeMail)(name, { cwd: cwd(), ...o });
266
+ });
261
267
  make("make:dto", ["m:dto"], "Create a class-validator DTO in src/dtos/<name>.dto.ts")
262
268
  .option("--root <dir>", "Folder under src/ to write to (also -rt)")
263
269
  .action((name, o) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@meghjs/cli",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "CLI for scaffolding and running Megh applications",
5
5
  "author": "Tareq Hossain",
6
6
  "license": "MIT",
@@ -52,7 +52,7 @@
52
52
  "vitest": "^4.1.12"
53
53
  },
54
54
  "peerDependencies": {
55
- "@meghjs/core": "^0.6.0"
55
+ "@meghjs/core": "^0.6.1"
56
56
  },
57
57
  "peerDependenciesMeta": {
58
58
  "@meghjs/core": {
@@ -71,5 +71,5 @@
71
71
  "publishConfig": {
72
72
  "access": "public"
73
73
  },
74
- "gitHead": "456b604c95c5aafcb9beabc46b3cc16946fa2176"
74
+ "gitHead": "7fff07fe185c332d74e223a30260b51218c9a60d"
75
75
  }
@@ -0,0 +1,37 @@
1
+ import { Mailable } from '@meghjs/core';
2
+
3
+ /**
4
+ * The "{Title}" email.
5
+ *
6
+ * Send it with the injected `Mailer`:
7
+ *
8
+ * @example
9
+ * constructor(private readonly mailer: Mailer) {}
10
+ *
11
+ * await this.mailer.to(user.email).send(new {ClassName}());
12
+ * await this.mailer.to(user.email).queue(new {ClassName}()); // needs app.useMail({ queue: true })
13
+ */
14
+ export class {ClassName} extends Mailable {
15
+ // Take the data the email needs in the constructor, e.g.
16
+ // constructor(private readonly user: User) {
17
+ // super();
18
+ // }
19
+
20
+ /** The subject, and optionally from, replyTo, cc and bcc. */
21
+ envelope() {
22
+ return { subject: '{Title}' };
23
+ }
24
+
25
+ /** The body: html, text or both. Each method here may be async. */
26
+ content() {
27
+ return {
28
+ html: '<p>{Title}</p>',
29
+ text: '{Title}',
30
+ };
31
+ }
32
+
33
+ /** Files to attach: { filename, content } or { path }. */
34
+ attachments() {
35
+ return [];
36
+ }
37
+ }
@@ -1,33 +1,88 @@
1
1
  import { AppService, type CreateInput, type PageRequest, type UpdateInput } from '@meghjs/core';
2
2
  import { {Model} } from '{modelImport}';
3
3
 
4
+ /**
5
+ * Reads and writes {Model} rows for the {Model} resource.
6
+ *
7
+ * Megh's container creates one instance and injects it wherever it is asked
8
+ * for, so a controller only declares it as a constructor parameter. Put the
9
+ * {Model} business rules here and keep the controller to HTTP concerns.
10
+ *
11
+ * @example
12
+ * constructor(private readonly {modelVar}Service: {ClassName}) {}
13
+ *
14
+ * const {modelVar} = await this.{modelVar}Service.findOrFail(id);
15
+ */
4
16
  @AppService
5
17
  export class {ClassName} {
6
- /** Every {modelVar}, ordered by {primaryKey}. */
18
+ /**
19
+ * Every {modelVar} row, ordered by `{primaryKey}`.
20
+ *
21
+ * Loads the whole table, so use {@link {ClassName}.paginate} for any table
22
+ * that can grow.
23
+ *
24
+ * @returns Every {Model}, an empty array when there are none.
25
+ */
7
26
  findAll() {
8
27
  return {Model}.query().orderBy('{primaryKey}').get();
9
28
  }
10
29
 
11
- /** One page of {modelVar} rows: `{ data, meta }`. */
30
+ /**
31
+ * One page of {modelVar} rows, ordered by `{primaryKey}`.
32
+ *
33
+ * @param request - `page` (from 1, default 1) and `perPage` (default 10).
34
+ * @returns `{ data, meta }`: the rows on this page, and `meta` with
35
+ * `total`, `page`, `perPage` and `lastPage`.
36
+ */
12
37
  paginate(request: PageRequest = {}) {
13
38
  return {Model}.query().orderBy('{primaryKey}').paginate(request);
14
39
  }
15
40
 
16
- /** The {modelVar} with this {primaryKey}, or `undefined`. */
41
+ /**
42
+ * The {modelVar} with this `{primaryKey}`, if there is one.
43
+ *
44
+ * @param id - The `{primaryKey}` to look up.
45
+ * @returns The {Model}, or `undefined` when no row has this `{primaryKey}`.
46
+ */
17
47
  find(id: {primaryKeyType}) {
18
48
  return {Model}.find(id);
19
49
  }
20
50
 
21
- /** The {modelVar} with this {primaryKey}; throws a 404 when there is none. */
51
+ /**
52
+ * The {modelVar} with this `{primaryKey}`, for when it must exist.
53
+ *
54
+ * @param id - The `{primaryKey}` to look up.
55
+ * @returns The {Model}.
56
+ * @throws NotFoundException when no row has this `{primaryKey}`; Megh
57
+ * answers it with a 404.
58
+ */
22
59
  findOrFail(id: {primaryKeyType}) {
23
60
  return {Model}.findOrFail(id);
24
61
  }
25
62
 
63
+ /**
64
+ * Insert a new {modelVar} row.
65
+ *
66
+ * @param input - The column values. Columns the database fills in, such as
67
+ * an auto-increment `{primaryKey}` or timestamps, may be left out.
68
+ * @returns The new {Model}, with the values the database filled in.
69
+ */
26
70
  create(input: CreateInput<typeof {Model}>) {
27
71
  return {Model}.create(input);
28
72
  }
29
73
 
30
- /** `save()` writes only the columns that changed. */
74
+ /**
75
+ * Change some columns of an existing {modelVar}.
76
+ *
77
+ * Fields that are `undefined` are skipped, so a partial update DTO only
78
+ * changes what the client sent, and `save()` writes only the columns whose
79
+ * value changed.
80
+ *
81
+ * @param id - The `{primaryKey}` of the {modelVar} to change.
82
+ * @param changes - The new column values.
83
+ * @returns The updated {Model}.
84
+ * @throws NotFoundException when no row has this `{primaryKey}` (a 404).
85
+ */
31
86
  async update(id: {primaryKeyType}, changes: UpdateInput<{Model}>) {
32
87
  const {modelVar} = await {Model}.findOrFail(id);
33
88
  // A DTO instance holds `undefined` for every field that was not sent.
@@ -35,6 +90,13 @@ export class {ClassName} {
35
90
  return {modelVar}.fill(sent).save();
36
91
  }
37
92
 
93
+ /**
94
+ * Delete a {modelVar}. With `softDeletes` on the model, this sets
95
+ * `deleted_at` instead of removing the row.
96
+ *
97
+ * @param id - The `{primaryKey}` of the {modelVar} to delete.
98
+ * @throws NotFoundException when no row has this `{primaryKey}` (a 404).
99
+ */
38
100
  async delete(id: {primaryKeyType}) {
39
101
  const {modelVar} = await {Model}.findOrFail(id);
40
102
  await {modelVar}.delete();