@meghjs/core 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.
Files changed (49) hide show
  1. package/README.md +62 -15
  2. package/dist/core/application.d.ts +50 -0
  3. package/dist/core/application.js +105 -0
  4. package/dist/core/application.js.map +1 -1
  5. package/dist/core/interfaces.d.ts +10 -0
  6. package/dist/core/router.d.ts +28 -0
  7. package/dist/core/router.js +26 -1
  8. package/dist/core/router.js.map +1 -1
  9. package/dist/core/types.d.ts +3 -0
  10. package/dist/index.d.ts +1 -0
  11. package/dist/index.js +2 -0
  12. package/dist/index.js.map +1 -1
  13. package/dist/mail/config.d.ts +141 -0
  14. package/dist/mail/config.js +199 -0
  15. package/dist/mail/config.js.map +1 -0
  16. package/dist/mail/errors.d.ts +4 -0
  17. package/dist/mail/errors.js +12 -0
  18. package/dist/mail/errors.js.map +1 -0
  19. package/dist/mail/http-transports.d.ts +44 -0
  20. package/dist/mail/http-transports.js +319 -0
  21. package/dist/mail/http-transports.js.map +1 -0
  22. package/dist/mail/index.d.ts +8 -0
  23. package/dist/mail/index.js +46 -0
  24. package/dist/mail/index.js.map +1 -0
  25. package/dist/mail/mailable.d.ts +34 -0
  26. package/dist/mail/mailable.js +38 -0
  27. package/dist/mail/mailable.js.map +1 -0
  28. package/dist/mail/mailer.d.ts +208 -0
  29. package/dist/mail/mailer.js +502 -0
  30. package/dist/mail/mailer.js.map +1 -0
  31. package/dist/mail/queue.d.ts +32 -0
  32. package/dist/mail/queue.js +59 -0
  33. package/dist/mail/queue.js.map +1 -0
  34. package/dist/mail/transports.d.ts +37 -0
  35. package/dist/mail/transports.js +152 -0
  36. package/dist/mail/transports.js.map +1 -0
  37. package/dist/mail/types.d.ts +95 -0
  38. package/dist/mail/types.js +3 -0
  39. package/dist/mail/types.js.map +1 -0
  40. package/dist/security/headers.d.ts +65 -0
  41. package/dist/security/headers.js +148 -0
  42. package/dist/security/headers.js.map +1 -0
  43. package/dist/security/index.d.ts +3 -0
  44. package/dist/security/index.js +5 -0
  45. package/dist/security/index.js.map +1 -1
  46. package/dist/security/rate-limit.d.ts +129 -0
  47. package/dist/security/rate-limit.js +260 -0
  48. package/dist/security/rate-limit.js.map +1 -0
  49. package/package.json +10 -13
@@ -0,0 +1,208 @@
1
+ import type { Constructor } from "../common/utils/common-utils";
2
+ import { type MailConfig } from "./config";
3
+ import { Mailable } from "./mailable";
4
+ import type { MailAddress, MailAddressLike, MailMessage, MailTransportResult, QueuedMessage, SentMessage } from "./types";
5
+ type Recipients = {
6
+ to: MailAddress[];
7
+ cc: MailAddress[];
8
+ bcc: MailAddress[];
9
+ };
10
+ type AddressInput = MailAddressLike | MailAddressLike[];
11
+ /**
12
+ * Sends {@link Mailable}s. Inject it like any service; every instance shares
13
+ * the configuration set by `app.useMail()` (or read from `MEGH_MAIL_*` when
14
+ * `useMail()` was not called).
15
+ *
16
+ * @example
17
+ * constructor(private readonly mailer: Mailer) {}
18
+ *
19
+ * await this.mailer.to(user.email).send(new WelcomeMail(user));
20
+ * await this.mailer.to(user.email).queue(new WelcomeMail(user)); // needs useMail({ queue })
21
+ * await this.mailer.mailer('log').to('dev@x.io').send(new WelcomeMail(user));
22
+ */
23
+ export declare class Mailer {
24
+ private static config;
25
+ private static readonly transports;
26
+ private static current;
27
+ private static mailQueue;
28
+ /** The named mailer to use; `undefined` means the default. */
29
+ private mailerName;
30
+ /**
31
+ * Set the mail configuration, merged over `MEGH_MAIL_*`. Called by
32
+ * `app.useMail()`; call it yourself outside a Megh app.
33
+ *
34
+ * With `queue` set, this also starts the worker that sends queued mail
35
+ * (unless `queue.worker` is `false`).
36
+ *
37
+ * @throws MailError when the configuration is invalid, e.g. in production
38
+ * with no mailer set.
39
+ */
40
+ static configure(options?: MailConfig): void;
41
+ /**
42
+ * Record messages instead of sending them, and get assertions on what was
43
+ * sent. Undo it with `restore()` on the result, or {@link Mailer.restore}.
44
+ *
45
+ * @example
46
+ * const mail = Mailer.fake();
47
+ * await service.register(user);
48
+ * mail.assertSent(WelcomeMail, (sent) => sent.hasTo(user.email));
49
+ */
50
+ static fake(): MailFake;
51
+ /** Stop faking; messages are sent again. */
52
+ static restore(): void;
53
+ /**
54
+ * Close the mail queue and every transport's connections. Called when the
55
+ * app closes.
56
+ */
57
+ static close(): Promise<void>;
58
+ /** Forget the configuration and transports, so the environment is read again. */
59
+ static reset(): Promise<void>;
60
+ /**
61
+ * The same mailer, sending through the named mailer instead of the default.
62
+ *
63
+ * @param name - A key of `mailers` in the configuration, e.g. `smtp` or `log`.
64
+ */
65
+ mailer(name: string): Mailer;
66
+ /** Start a message to these recipients. */
67
+ to(...addresses: AddressInput[]): PendingMail;
68
+ /** Start a message with these carbon-copy recipients. */
69
+ cc(...addresses: AddressInput[]): PendingMail;
70
+ /** Start a message with these blind-copy recipients. */
71
+ bcc(...addresses: AddressInput[]): PendingMail;
72
+ /**
73
+ * Send a mailable to the recipients its `envelope()` names.
74
+ *
75
+ * @returns The mailer used, the built message and the provider's reply.
76
+ * @throws MailError when the message has no sender, no recipients or no body.
77
+ */
78
+ send(mailable: Mailable): Promise<SentMessage>;
79
+ /** Queue a mailable for the recipients its `envelope()` names. See {@link PendingMail.queue}. */
80
+ queue(mailable: Mailable): Promise<QueuedMessage>;
81
+ /** Queue a mailable to be sent later. See {@link PendingMail.later}. */
82
+ later(delay: number | Date, mailable: Mailable): Promise<QueuedMessage>;
83
+ /** @internal Build and send (or record) one message. */
84
+ static dispatch(mailerName: string | undefined, recipients: Recipients, mailable: Mailable): Promise<SentMessage>;
85
+ /** @internal Build one message and queue it (or record it). */
86
+ static dispatchQueued(mailerName: string | undefined, recipients: Recipients, mailable: Mailable, delay: number): Promise<QueuedMessage>;
87
+ /** @internal Send a built message through a named mailer. Used by the queue worker. */
88
+ static deliver(name: string, message: MailMessage): Promise<MailTransportResult | void>;
89
+ private static resolve;
90
+ }
91
+ /**
92
+ * A message being addressed: `mailer.to(...).cc(...).send(mailable)`.
93
+ * Each method adds recipients and returns the same object.
94
+ */
95
+ export declare class PendingMail {
96
+ private readonly mailerName?;
97
+ private readonly recipients;
98
+ constructor(mailerName?: string | undefined);
99
+ /** Add recipients. */
100
+ to(...addresses: AddressInput[]): this;
101
+ /** Add carbon-copy recipients. */
102
+ cc(...addresses: AddressInput[]): this;
103
+ /** Add blind-copy recipients. */
104
+ bcc(...addresses: AddressInput[]): this;
105
+ /**
106
+ * Build the mailable and send it now.
107
+ *
108
+ * @returns The mailer used, the built message and the provider's reply.
109
+ * @throws MailError when the message has no sender, no recipients or no body.
110
+ */
111
+ send(mailable: Mailable): Promise<SentMessage>;
112
+ /**
113
+ * Build the mailable now and send it from the mail queue's worker. The
114
+ * job holds the built message, so the mailable is not needed there; an
115
+ * attachment given by `path` must exist where the worker runs.
116
+ *
117
+ * @returns The mailer, the built message and the job ID.
118
+ * @throws MailError when queueing is off (`useMail({ queue })`), or the
119
+ * message has no sender, no recipients or no body.
120
+ */
121
+ queue(mailable: Mailable): Promise<QueuedMessage>;
122
+ /**
123
+ * Like {@link PendingMail.queue}, but sent after a delay.
124
+ *
125
+ * @param delay - Milliseconds to wait, or the time to send at. A time in
126
+ * the past sends straight away.
127
+ */
128
+ later(delay: number | Date, mailable: Mailable): Promise<QueuedMessage>;
129
+ }
130
+ /** @internal Turn a mailable and its recipients into a message. */
131
+ export declare function buildMessage(mailable: Mailable, recipients: Recipients, defaultFrom?: MailAddressLike): Promise<MailMessage>;
132
+ /** Normalize one address; rejects line breaks, which could inject headers. */
133
+ export declare function parseAddress(input: MailAddressLike): MailAddress;
134
+ /** One message recorded by {@link MailFake}, with helpers for assertions. */
135
+ export declare class SentMail<T extends Mailable = Mailable> {
136
+ /** The mailer it would have gone through. */
137
+ readonly mailer: string;
138
+ readonly mailable: T;
139
+ readonly message: MailMessage;
140
+ /** For queued mail: milliseconds until it would be sent. */
141
+ readonly delay: number;
142
+ constructor(
143
+ /** The mailer it would have gone through. */
144
+ mailer: string, mailable: T, message: MailMessage,
145
+ /** For queued mail: milliseconds until it would be sent. */
146
+ delay?: number);
147
+ /** Whether `address` is among the `to` recipients (case-insensitive). */
148
+ hasTo(address: MailAddressLike): boolean;
149
+ /** Whether `address` is among the `cc` recipients. */
150
+ hasCc(address: MailAddressLike): boolean;
151
+ /** Whether `address` is among the `bcc` recipients. */
152
+ hasBcc(address: MailAddressLike): boolean;
153
+ /** Whether the message comes from `address`. */
154
+ hasFrom(address: MailAddressLike): boolean;
155
+ }
156
+ type Filter<T extends Mailable> = (sent: SentMail<T>) => boolean;
157
+ /**
158
+ * Returned by {@link Mailer.fake}: what would have been sent or queued, and
159
+ * assertions that throw a descriptive error when they fail (any test runner
160
+ * works).
161
+ */
162
+ export declare class MailFake {
163
+ /** Every message sent with `send()`, oldest first. */
164
+ readonly sent: SentMail[];
165
+ /** Every message queued with `queue()` or `later()`, oldest first. */
166
+ readonly queued: SentMail[];
167
+ /** @internal */
168
+ record(mail: SentMail): void;
169
+ /** @internal */
170
+ recordQueued(mail: SentMail): void;
171
+ /** The sent messages of one mailable class, optionally filtered. */
172
+ sentOf<T extends Mailable>(type: Constructor<T>, filter?: Filter<T>): SentMail<T>[];
173
+ /** The queued messages of one mailable class, optionally filtered. */
174
+ queuedOf<T extends Mailable>(type: Constructor<T>, filter?: Filter<T>): SentMail<T>[];
175
+ /**
176
+ * Assert that a mailable of this class was sent with `send()`.
177
+ *
178
+ * @param filterOrTimes - A check a match must pass, or the exact number
179
+ * of times it must have been sent.
180
+ */
181
+ assertSent<T extends Mailable>(type: Constructor<T>, filterOrTimes?: Filter<T> | number): void;
182
+ /** Assert that no mailable of this class (matching `filter`, if given) was sent. */
183
+ assertNotSent<T extends Mailable>(type: Constructor<T>, filter?: Filter<T>): void;
184
+ /**
185
+ * Assert that a mailable of this class was queued with `queue()` or `later()`.
186
+ *
187
+ * @param filterOrTimes - A check a match must pass (`sent.delay` holds the
188
+ * delay in milliseconds), or the exact number of times it must have been
189
+ * queued.
190
+ */
191
+ assertQueued<T extends Mailable>(type: Constructor<T>, filterOrTimes?: Filter<T> | number): void;
192
+ /** Assert that no mailable of this class (matching `filter`, if given) was queued. */
193
+ assertNotQueued<T extends Mailable>(type: Constructor<T>, filter?: Filter<T>): void;
194
+ /** Assert that nothing was sent with `send()`. */
195
+ assertNothingSent(): void;
196
+ /** Assert that nothing was queued. */
197
+ assertNothingQueued(): void;
198
+ /** Assert how many messages were sent with `send()` in all. */
199
+ assertSentCount(count: number): void;
200
+ /** Stop faking; same as {@link Mailer.restore}. */
201
+ restore(): void;
202
+ private expect;
203
+ private expectNone;
204
+ /** Point out a mailable that was queued when `sent` was expected, or the reverse. */
205
+ private hint;
206
+ private summary;
207
+ }
208
+ export {};