@plinthjs/contracts 0.1.0 → 0.1.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.
- package/LICENSE +1 -1
- package/README.md +2 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +37 -42
- package/dist/index.d.ts +37 -42
- package/dist/index.js.map +1 -1
- package/package.json +3 -4
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @plinthjs/contracts
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
interfaces and type aliases that the other
|
|
3
|
+
Plinth's interface-only foundation. It exports the structural
|
|
4
|
+
interfaces and type aliases that the other Plinth packages depend on, so they can stay decoupled from
|
|
5
5
|
one another. The package is zero-runtime and dependency-free: the only value it exports is `VERSION`.
|
|
6
6
|
|
|
7
7
|
## Install
|
package/dist/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AA2BO,IAAM,OAAA,GAAU","file":"index.cjs","sourcesContent":["/**\n * `@plinthjs/contracts` — the interface-only foundation
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AA2BO,IAAM,OAAA,GAAU","file":"index.cjs","sourcesContent":["/**\n * `@plinthjs/contracts` — the interface-only foundation. This\n * package is zero-runtime and dependency-free: it exports the structural interfaces and type aliases\n * other Plinth packages depend on to decouple from one another. The only runtime export is\n * {@link VERSION}.\n */\n\nexport type { Arrayable, Jsonable, Objectable, Renderable } from './support'\nexport type { HasErrorBag, HasHttpStatus } from './http'\nexport type { HashOptions, Hasher } from './hashing'\nexport type { Encrypter } from './encryption'\nexport type {\n Authenticatable,\n Credentials,\n Guard,\n Rememberable,\n StatefulGuard,\n UserProvider,\n} from './auth'\nexport type { CacheRepository, CacheStore } from './cache'\nexport type { JobMiddleware, Queueable, QueueJob, ShouldQueue } from './queue'\nexport type { Mailer, MailableContract } from './mail'\nexport type { Disk } from './filesystem'\nexport type { Container, Identifier, Newable } from './container'\nexport type { Cast, CastEncrypter } from './casts'\n\n/** The Plinth version this build of `contracts` ships with. */\nexport const VERSION = '0.1.0'\n"]}
|
package/dist/index.d.cts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Core support contracts — the
|
|
2
|
+
* Core support contracts — the interfaces. These tiny,
|
|
3
3
|
* structural shapes let any value advertise that it can be turned into an array
|
|
4
4
|
* ({@link Arrayable}), serialized to JSON ({@link Jsonable}), or rendered to a string
|
|
5
5
|
* ({@link Renderable}) without coupling the consumer to a concrete type.
|
|
6
6
|
*/
|
|
7
7
|
/**
|
|
8
|
-
* A value convertible to an array
|
|
8
|
+
* A value convertible to an array.
|
|
9
9
|
* Generic over the element type so `Arrayable<User>` yields `User[]`.
|
|
10
10
|
*/
|
|
11
11
|
interface Arrayable<T = unknown> {
|
|
@@ -13,7 +13,7 @@ interface Arrayable<T = unknown> {
|
|
|
13
13
|
toArray(): T[];
|
|
14
14
|
}
|
|
15
15
|
/**
|
|
16
|
-
* A value convertible to a plain keyed object — the
|
|
16
|
+
* A value convertible to a plain keyed object — following the conventional design
|
|
17
17
|
* object-shaped variant, for things that flatten to a record rather than a list.
|
|
18
18
|
*/
|
|
19
19
|
interface Objectable<T = unknown> {
|
|
@@ -21,7 +21,7 @@ interface Objectable<T = unknown> {
|
|
|
21
21
|
toObject(): Record<string, T>;
|
|
22
22
|
}
|
|
23
23
|
/**
|
|
24
|
-
* A value convertible to a JSON-safe representation — the
|
|
24
|
+
* A value convertible to a JSON-safe representation — following the conventional design
|
|
25
25
|
* equivalent. Returns the value to be serialized (not the JSON string) so callers control encoding.
|
|
26
26
|
*/
|
|
27
27
|
interface Jsonable {
|
|
@@ -29,7 +29,7 @@ interface Jsonable {
|
|
|
29
29
|
toJSON(): unknown;
|
|
30
30
|
}
|
|
31
31
|
/**
|
|
32
|
-
* A value that can render itself to a string — the
|
|
32
|
+
* A value that can render itself to a string — following the conventional design
|
|
33
33
|
* equivalent (e.g. a view or a mailable preview).
|
|
34
34
|
*/
|
|
35
35
|
interface Renderable {
|
|
@@ -53,7 +53,7 @@ interface HasHttpStatus {
|
|
|
53
53
|
}
|
|
54
54
|
/**
|
|
55
55
|
* An error carrying a `field → messages` bag — the seam the handler surfaces as the JSON `errors`
|
|
56
|
-
* payload (e.g. from a validation failure). Mirrors
|
|
56
|
+
* payload (e.g. from a validation failure). Mirrors the conventional `MessageBag`-shaped error output.
|
|
57
57
|
*/
|
|
58
58
|
interface HasErrorBag {
|
|
59
59
|
/** Validation/field errors keyed by field name, each a list of human-readable messages. */
|
|
@@ -61,17 +61,17 @@ interface HasErrorBag {
|
|
|
61
61
|
}
|
|
62
62
|
|
|
63
63
|
/**
|
|
64
|
-
* Hashing contract
|
|
64
|
+
* Hashing contract. A {@link Hasher}
|
|
65
65
|
* hashes secrets (passwords) one-way, verifies a candidate against a stored hash in constant time,
|
|
66
66
|
* and reports when a stored hash should be recomputed because its cost parameters have changed.
|
|
67
67
|
*/
|
|
68
68
|
/**
|
|
69
|
-
* Tunable hashing cost options
|
|
69
|
+
* Tunable hashing cost options. Expressed openly
|
|
70
70
|
* as a record so each driver (bcrypt, argon, scrypt) can accept its own cost knobs.
|
|
71
71
|
*/
|
|
72
72
|
type HashOptions = Record<string, unknown>;
|
|
73
73
|
/**
|
|
74
|
-
* The password hasher
|
|
74
|
+
* The password hasher contract
|
|
75
75
|
* surface. Implementations are expected to use a self-describing hash format so parameters can be
|
|
76
76
|
* detected by {@link Hasher.needsRehash} and evolve over time.
|
|
77
77
|
*/
|
|
@@ -85,13 +85,13 @@ interface Hasher {
|
|
|
85
85
|
}
|
|
86
86
|
|
|
87
87
|
/**
|
|
88
|
-
* Encryption contract
|
|
88
|
+
* Encryption contract. An
|
|
89
89
|
* {@link Encrypter} performs authenticated symmetric encryption: any JSON-safe value is serialized
|
|
90
90
|
* and encrypted to an opaque string by {@link Encrypter.encrypt}, and revived by
|
|
91
91
|
* {@link Encrypter.decrypt} (which is expected to throw if the payload is tampered or the key wrong).
|
|
92
92
|
*/
|
|
93
93
|
/**
|
|
94
|
-
* The encrypter
|
|
94
|
+
* The encrypter contract
|
|
95
95
|
* surface. Values round-trip through JSON, so {@link Encrypter.decrypt} returns `unknown`.
|
|
96
96
|
*/
|
|
97
97
|
interface Encrypter {
|
|
@@ -102,12 +102,12 @@ interface Encrypter {
|
|
|
102
102
|
}
|
|
103
103
|
|
|
104
104
|
/**
|
|
105
|
-
* Authentication contracts — the
|
|
105
|
+
* Authentication contracts — the interfaces.
|
|
106
106
|
* {@link Authenticatable} is a user that can be authenticated; {@link UserProvider} retrieves and
|
|
107
107
|
* validates users from storage; {@link Guard} reads who the current user is; {@link StatefulGuard}
|
|
108
108
|
* also logs them in and out across requests; {@link Rememberable} adds "remember me" persistence.
|
|
109
109
|
*/
|
|
110
|
-
/** A user that can be authenticated
|
|
110
|
+
/** A user that can be authenticated. */
|
|
111
111
|
interface Authenticatable {
|
|
112
112
|
/** The unique identifier (primary key) for the user. */
|
|
113
113
|
getAuthIdentifier(): string | number;
|
|
@@ -116,10 +116,10 @@ interface Authenticatable {
|
|
|
116
116
|
/** The hashed password used to validate credentials. */
|
|
117
117
|
getAuthPassword(): string;
|
|
118
118
|
}
|
|
119
|
-
/** Login credentials — typically `{ email, password }`.
|
|
119
|
+
/** Login credentials — typically `{ email, password }`. */
|
|
120
120
|
type Credentials = Record<string, unknown>;
|
|
121
121
|
/**
|
|
122
|
-
* A user that supports "remember me" persistence — the
|
|
122
|
+
* A user that supports "remember me" persistence — the remember-token methods on
|
|
123
123
|
* `Authenticatable`. Kept separate so a user can opt into it independently.
|
|
124
124
|
*/
|
|
125
125
|
interface Rememberable {
|
|
@@ -129,7 +129,7 @@ interface Rememberable {
|
|
|
129
129
|
setRememberToken(token: string): void;
|
|
130
130
|
}
|
|
131
131
|
/**
|
|
132
|
-
* Retrieves and validates users from storage — the
|
|
132
|
+
* Retrieves and validates users from storage — following the conventional design
|
|
133
133
|
* equivalent. The seam between a guard and however users are persisted.
|
|
134
134
|
*/
|
|
135
135
|
interface UserProvider {
|
|
@@ -144,7 +144,7 @@ interface UserProvider {
|
|
|
144
144
|
/** Whether `credentials` validate against `user` (constant-time password check). */
|
|
145
145
|
validateCredentials(user: Authenticatable, credentials: Credentials): Promise<boolean>;
|
|
146
146
|
}
|
|
147
|
-
/** A read-only authentication guard
|
|
147
|
+
/** A read-only authentication guard. */
|
|
148
148
|
interface Guard {
|
|
149
149
|
/** Whether a user is authenticated. */
|
|
150
150
|
check(): Promise<boolean>;
|
|
@@ -160,8 +160,7 @@ interface Guard {
|
|
|
160
160
|
setUser(user: Authenticatable): void;
|
|
161
161
|
}
|
|
162
162
|
/**
|
|
163
|
-
* A guard that can also log users in and out across requests
|
|
164
|
-
* `Illuminate\Contracts\Auth\StatefulGuard` equivalent.
|
|
163
|
+
* A guard that can also log users in and out across requests.
|
|
165
164
|
*/
|
|
166
165
|
interface StatefulGuard extends Guard {
|
|
167
166
|
/** Validate credentials and, on success, log the user in. */
|
|
@@ -177,14 +176,13 @@ interface StatefulGuard extends Guard {
|
|
|
177
176
|
}
|
|
178
177
|
|
|
179
178
|
/**
|
|
180
|
-
* Cache contracts — the
|
|
179
|
+
* Cache contracts — the interfaces. {@link CacheStore} is the
|
|
181
180
|
* lowest layer (the swappable backend: array, file, Redis); {@link CacheRepository} is the
|
|
182
181
|
* user-facing superset that adds the ergonomic helpers (`remember`, `pull`, `has`) on top. Every
|
|
183
|
-
* method is async so a store may be backed by I/O, and TTLs are expressed in **seconds
|
|
184
|
-
* unit). Values are generic over `unknown`.
|
|
182
|
+
* method is async so a store may be backed by I/O, and TTLs are expressed in **seconds**. Values are generic over `unknown`.
|
|
185
183
|
*/
|
|
186
184
|
/**
|
|
187
|
-
* The cache store
|
|
185
|
+
* The cache store. The minimal persistence
|
|
188
186
|
* surface every backend implements; the {@link CacheRepository} is layered over it.
|
|
189
187
|
*/
|
|
190
188
|
interface CacheStore {
|
|
@@ -200,8 +198,7 @@ interface CacheStore {
|
|
|
200
198
|
flush(): Promise<boolean>;
|
|
201
199
|
}
|
|
202
200
|
/**
|
|
203
|
-
* The cache repository
|
|
204
|
-
* facade surface. A superset of {@link CacheStore} adding the compute-on-miss `remember` family,
|
|
201
|
+
* The cache repository. A superset of {@link CacheStore} adding the compute-on-miss `remember` family,
|
|
205
202
|
* the read-and-delete `pull`, and existence/atomic-counter helpers.
|
|
206
203
|
*/
|
|
207
204
|
interface CacheRepository extends CacheStore {
|
|
@@ -222,19 +219,17 @@ interface CacheRepository extends CacheStore {
|
|
|
222
219
|
}
|
|
223
220
|
|
|
224
221
|
/**
|
|
225
|
-
* Queue contracts — the
|
|
226
|
-
* interfaces. {@link ShouldQueue} is the marker that opts work into the queue; {@link QueueJob} is
|
|
222
|
+
* Queue contracts — the queueing and job interfaces. {@link ShouldQueue} is the marker that opts work into the queue; {@link QueueJob} is
|
|
227
223
|
* the unit of deferred work whose `handle()` a driver runs; {@link JobMiddleware} wraps that call
|
|
228
224
|
* with cross-cutting concerns. {@link Queueable} is the alias used where a queueable job is expected.
|
|
229
225
|
*/
|
|
230
226
|
/**
|
|
231
|
-
* Marker that a class should be dispatched onto a queue rather than run inline
|
|
232
|
-
* `Illuminate\Contracts\Queue\ShouldQueue` equivalent. Intentionally empty: it tags intent only.
|
|
227
|
+
* Marker that a class should be dispatched onto a queue rather than run inline. Intentionally empty: it tags intent only.
|
|
233
228
|
*/
|
|
234
229
|
interface ShouldQueue {
|
|
235
230
|
}
|
|
236
231
|
/**
|
|
237
|
-
* The unit of deferred work — the `ShouldQueue`
|
|
232
|
+
* The unit of deferred work — the `ShouldQueue` +. A driver
|
|
238
233
|
* `await`s {@link QueueJob.handle}; an optional {@link QueueJob.tries} bounds attempts before the
|
|
239
234
|
* job is treated as failed, and {@link QueueJob.middleware} wraps the call to `handle`.
|
|
240
235
|
*/
|
|
@@ -249,21 +244,21 @@ interface QueueJob {
|
|
|
249
244
|
/** Alias of {@link QueueJob} — used where a queueable job is expected (the `Queueable` concept). */
|
|
250
245
|
type Queueable = QueueJob;
|
|
251
246
|
/**
|
|
252
|
-
* One link in a job's middleware pipeline — the
|
|
247
|
+
* One link in a job's middleware pipeline — the job-middleware (`handle($job, $next)`)
|
|
253
248
|
* equivalent, expressed as a function. Awaiting `next()` runs the rest of the pipeline (and
|
|
254
249
|
* ultimately `handle`); skipping it short-circuits the job.
|
|
255
250
|
*/
|
|
256
251
|
type JobMiddleware = (job: QueueJob, next: () => Promise<void>) => Promise<void> | void;
|
|
257
252
|
|
|
258
253
|
/**
|
|
259
|
-
* Mail contracts — the
|
|
254
|
+
* Mail contracts — the interfaces. A {@link MailableContract}
|
|
260
255
|
* is a self-describing email that configures itself via `build()` and can `render()` itself; a
|
|
261
256
|
* {@link Mailer} dispatches one through whatever transport backs it. Kept transport-agnostic so the
|
|
262
257
|
* sender never cares which delivery mechanism is wired up.
|
|
263
258
|
*/
|
|
264
259
|
|
|
265
260
|
/**
|
|
266
|
-
* A self-describing email
|
|
261
|
+
* A self-describing email. {@link
|
|
267
262
|
* MailableContract.build} configures the message (recipients, subject, body) before it is sent;
|
|
268
263
|
* {@link Renderable.render} produces its rendered form for previewing or inlining.
|
|
269
264
|
*/
|
|
@@ -272,7 +267,7 @@ interface MailableContract extends Renderable {
|
|
|
272
267
|
build(): void;
|
|
273
268
|
}
|
|
274
269
|
/**
|
|
275
|
-
* The mailer
|
|
270
|
+
* The mailer contract.
|
|
276
271
|
* {@link Mailer.send} runs a mailable's lifecycle and dispatches it through the bound transport.
|
|
277
272
|
*/
|
|
278
273
|
interface Mailer {
|
|
@@ -281,14 +276,14 @@ interface Mailer {
|
|
|
281
276
|
}
|
|
282
277
|
|
|
283
278
|
/**
|
|
284
|
-
* Filesystem contract
|
|
279
|
+
* Filesystem contract. A
|
|
285
280
|
* {@link Disk} is a single named storage location (local directory, in-memory tree, cloud bucket)
|
|
286
281
|
* exposed as a uniform async API, so the layer above never cares which driver backs it. This is the
|
|
287
282
|
* common read/write/exists/delete/list subset; concrete disks may offer more. Paths are POSIX-style
|
|
288
283
|
* and relative to the disk root.
|
|
289
284
|
*/
|
|
290
285
|
/**
|
|
291
|
-
* The core filesystem surface — the common subset of
|
|
286
|
+
* The core filesystem surface — the common subset of what filesystems share.
|
|
292
287
|
* Every method is async so a driver may be backed by network or disk I/O.
|
|
293
288
|
*/
|
|
294
289
|
interface Disk {
|
|
@@ -305,7 +300,7 @@ interface Disk {
|
|
|
305
300
|
}
|
|
306
301
|
|
|
307
302
|
/**
|
|
308
|
-
* Container contract
|
|
303
|
+
* Container contract. A
|
|
309
304
|
* {@link Container} resolves dependencies by identifier (a string/symbol token or a class
|
|
310
305
|
* constructor): {@link Container.bind} registers a factory, {@link Container.singleton} registers a
|
|
311
306
|
* shared one, {@link Container.make} resolves it, and {@link Container.bound} reports registration.
|
|
@@ -319,7 +314,7 @@ type Newable<T = unknown> = new (...args: any[]) => T;
|
|
|
319
314
|
/** A thing that can identify a binding: a string/symbol token or a class constructor. */
|
|
320
315
|
type Identifier<T = unknown> = string | symbol | Newable<T>;
|
|
321
316
|
/**
|
|
322
|
-
* The service container
|
|
317
|
+
* The service container. The minimal
|
|
323
318
|
* bind/resolve surface application code holds; concrete containers add aliasing, tagging, and
|
|
324
319
|
* contextual binding on top.
|
|
325
320
|
*/
|
|
@@ -335,7 +330,7 @@ interface Container {
|
|
|
335
330
|
}
|
|
336
331
|
|
|
337
332
|
/**
|
|
338
|
-
* Cast contracts
|
|
333
|
+
* Cast contracts.
|
|
339
334
|
* A {@link Cast} transforms an attribute between its database-shaped value and its in-memory
|
|
340
335
|
* representation on read/write; {@link CastEncrypter} is the minimal encrypt/decrypt surface an
|
|
341
336
|
* encrypting cast needs. The owning model is passed as `unknown` to keep this package decoupled.
|
|
@@ -363,13 +358,13 @@ interface CastEncrypter {
|
|
|
363
358
|
}
|
|
364
359
|
|
|
365
360
|
/**
|
|
366
|
-
* `@plinthjs/contracts` — the interface-only foundation
|
|
361
|
+
* `@plinthjs/contracts` — the interface-only foundation. This
|
|
367
362
|
* package is zero-runtime and dependency-free: it exports the structural interfaces and type aliases
|
|
368
|
-
* other
|
|
363
|
+
* other Plinth packages depend on to decouple from one another. The only runtime export is
|
|
369
364
|
* {@link VERSION}.
|
|
370
365
|
*/
|
|
371
366
|
|
|
372
|
-
/** The
|
|
367
|
+
/** The Plinth version this build of `contracts` ships with. */
|
|
373
368
|
declare const VERSION = "0.1.0";
|
|
374
369
|
|
|
375
370
|
export { type Arrayable, type Authenticatable, type CacheRepository, type CacheStore, type Cast, type CastEncrypter, type Container, type Credentials, type Disk, type Encrypter, type Guard, type HasErrorBag, type HasHttpStatus, type HashOptions, type Hasher, type Identifier, type JobMiddleware, type Jsonable, type MailableContract, type Mailer, type Newable, type Objectable, type QueueJob, type Queueable, type Rememberable, type Renderable, type ShouldQueue, type StatefulGuard, type UserProvider, VERSION };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Core support contracts — the
|
|
2
|
+
* Core support contracts — the interfaces. These tiny,
|
|
3
3
|
* structural shapes let any value advertise that it can be turned into an array
|
|
4
4
|
* ({@link Arrayable}), serialized to JSON ({@link Jsonable}), or rendered to a string
|
|
5
5
|
* ({@link Renderable}) without coupling the consumer to a concrete type.
|
|
6
6
|
*/
|
|
7
7
|
/**
|
|
8
|
-
* A value convertible to an array
|
|
8
|
+
* A value convertible to an array.
|
|
9
9
|
* Generic over the element type so `Arrayable<User>` yields `User[]`.
|
|
10
10
|
*/
|
|
11
11
|
interface Arrayable<T = unknown> {
|
|
@@ -13,7 +13,7 @@ interface Arrayable<T = unknown> {
|
|
|
13
13
|
toArray(): T[];
|
|
14
14
|
}
|
|
15
15
|
/**
|
|
16
|
-
* A value convertible to a plain keyed object — the
|
|
16
|
+
* A value convertible to a plain keyed object — following the conventional design
|
|
17
17
|
* object-shaped variant, for things that flatten to a record rather than a list.
|
|
18
18
|
*/
|
|
19
19
|
interface Objectable<T = unknown> {
|
|
@@ -21,7 +21,7 @@ interface Objectable<T = unknown> {
|
|
|
21
21
|
toObject(): Record<string, T>;
|
|
22
22
|
}
|
|
23
23
|
/**
|
|
24
|
-
* A value convertible to a JSON-safe representation — the
|
|
24
|
+
* A value convertible to a JSON-safe representation — following the conventional design
|
|
25
25
|
* equivalent. Returns the value to be serialized (not the JSON string) so callers control encoding.
|
|
26
26
|
*/
|
|
27
27
|
interface Jsonable {
|
|
@@ -29,7 +29,7 @@ interface Jsonable {
|
|
|
29
29
|
toJSON(): unknown;
|
|
30
30
|
}
|
|
31
31
|
/**
|
|
32
|
-
* A value that can render itself to a string — the
|
|
32
|
+
* A value that can render itself to a string — following the conventional design
|
|
33
33
|
* equivalent (e.g. a view or a mailable preview).
|
|
34
34
|
*/
|
|
35
35
|
interface Renderable {
|
|
@@ -53,7 +53,7 @@ interface HasHttpStatus {
|
|
|
53
53
|
}
|
|
54
54
|
/**
|
|
55
55
|
* An error carrying a `field → messages` bag — the seam the handler surfaces as the JSON `errors`
|
|
56
|
-
* payload (e.g. from a validation failure). Mirrors
|
|
56
|
+
* payload (e.g. from a validation failure). Mirrors the conventional `MessageBag`-shaped error output.
|
|
57
57
|
*/
|
|
58
58
|
interface HasErrorBag {
|
|
59
59
|
/** Validation/field errors keyed by field name, each a list of human-readable messages. */
|
|
@@ -61,17 +61,17 @@ interface HasErrorBag {
|
|
|
61
61
|
}
|
|
62
62
|
|
|
63
63
|
/**
|
|
64
|
-
* Hashing contract
|
|
64
|
+
* Hashing contract. A {@link Hasher}
|
|
65
65
|
* hashes secrets (passwords) one-way, verifies a candidate against a stored hash in constant time,
|
|
66
66
|
* and reports when a stored hash should be recomputed because its cost parameters have changed.
|
|
67
67
|
*/
|
|
68
68
|
/**
|
|
69
|
-
* Tunable hashing cost options
|
|
69
|
+
* Tunable hashing cost options. Expressed openly
|
|
70
70
|
* as a record so each driver (bcrypt, argon, scrypt) can accept its own cost knobs.
|
|
71
71
|
*/
|
|
72
72
|
type HashOptions = Record<string, unknown>;
|
|
73
73
|
/**
|
|
74
|
-
* The password hasher
|
|
74
|
+
* The password hasher contract
|
|
75
75
|
* surface. Implementations are expected to use a self-describing hash format so parameters can be
|
|
76
76
|
* detected by {@link Hasher.needsRehash} and evolve over time.
|
|
77
77
|
*/
|
|
@@ -85,13 +85,13 @@ interface Hasher {
|
|
|
85
85
|
}
|
|
86
86
|
|
|
87
87
|
/**
|
|
88
|
-
* Encryption contract
|
|
88
|
+
* Encryption contract. An
|
|
89
89
|
* {@link Encrypter} performs authenticated symmetric encryption: any JSON-safe value is serialized
|
|
90
90
|
* and encrypted to an opaque string by {@link Encrypter.encrypt}, and revived by
|
|
91
91
|
* {@link Encrypter.decrypt} (which is expected to throw if the payload is tampered or the key wrong).
|
|
92
92
|
*/
|
|
93
93
|
/**
|
|
94
|
-
* The encrypter
|
|
94
|
+
* The encrypter contract
|
|
95
95
|
* surface. Values round-trip through JSON, so {@link Encrypter.decrypt} returns `unknown`.
|
|
96
96
|
*/
|
|
97
97
|
interface Encrypter {
|
|
@@ -102,12 +102,12 @@ interface Encrypter {
|
|
|
102
102
|
}
|
|
103
103
|
|
|
104
104
|
/**
|
|
105
|
-
* Authentication contracts — the
|
|
105
|
+
* Authentication contracts — the interfaces.
|
|
106
106
|
* {@link Authenticatable} is a user that can be authenticated; {@link UserProvider} retrieves and
|
|
107
107
|
* validates users from storage; {@link Guard} reads who the current user is; {@link StatefulGuard}
|
|
108
108
|
* also logs them in and out across requests; {@link Rememberable} adds "remember me" persistence.
|
|
109
109
|
*/
|
|
110
|
-
/** A user that can be authenticated
|
|
110
|
+
/** A user that can be authenticated. */
|
|
111
111
|
interface Authenticatable {
|
|
112
112
|
/** The unique identifier (primary key) for the user. */
|
|
113
113
|
getAuthIdentifier(): string | number;
|
|
@@ -116,10 +116,10 @@ interface Authenticatable {
|
|
|
116
116
|
/** The hashed password used to validate credentials. */
|
|
117
117
|
getAuthPassword(): string;
|
|
118
118
|
}
|
|
119
|
-
/** Login credentials — typically `{ email, password }`.
|
|
119
|
+
/** Login credentials — typically `{ email, password }`. */
|
|
120
120
|
type Credentials = Record<string, unknown>;
|
|
121
121
|
/**
|
|
122
|
-
* A user that supports "remember me" persistence — the
|
|
122
|
+
* A user that supports "remember me" persistence — the remember-token methods on
|
|
123
123
|
* `Authenticatable`. Kept separate so a user can opt into it independently.
|
|
124
124
|
*/
|
|
125
125
|
interface Rememberable {
|
|
@@ -129,7 +129,7 @@ interface Rememberable {
|
|
|
129
129
|
setRememberToken(token: string): void;
|
|
130
130
|
}
|
|
131
131
|
/**
|
|
132
|
-
* Retrieves and validates users from storage — the
|
|
132
|
+
* Retrieves and validates users from storage — following the conventional design
|
|
133
133
|
* equivalent. The seam between a guard and however users are persisted.
|
|
134
134
|
*/
|
|
135
135
|
interface UserProvider {
|
|
@@ -144,7 +144,7 @@ interface UserProvider {
|
|
|
144
144
|
/** Whether `credentials` validate against `user` (constant-time password check). */
|
|
145
145
|
validateCredentials(user: Authenticatable, credentials: Credentials): Promise<boolean>;
|
|
146
146
|
}
|
|
147
|
-
/** A read-only authentication guard
|
|
147
|
+
/** A read-only authentication guard. */
|
|
148
148
|
interface Guard {
|
|
149
149
|
/** Whether a user is authenticated. */
|
|
150
150
|
check(): Promise<boolean>;
|
|
@@ -160,8 +160,7 @@ interface Guard {
|
|
|
160
160
|
setUser(user: Authenticatable): void;
|
|
161
161
|
}
|
|
162
162
|
/**
|
|
163
|
-
* A guard that can also log users in and out across requests
|
|
164
|
-
* `Illuminate\Contracts\Auth\StatefulGuard` equivalent.
|
|
163
|
+
* A guard that can also log users in and out across requests.
|
|
165
164
|
*/
|
|
166
165
|
interface StatefulGuard extends Guard {
|
|
167
166
|
/** Validate credentials and, on success, log the user in. */
|
|
@@ -177,14 +176,13 @@ interface StatefulGuard extends Guard {
|
|
|
177
176
|
}
|
|
178
177
|
|
|
179
178
|
/**
|
|
180
|
-
* Cache contracts — the
|
|
179
|
+
* Cache contracts — the interfaces. {@link CacheStore} is the
|
|
181
180
|
* lowest layer (the swappable backend: array, file, Redis); {@link CacheRepository} is the
|
|
182
181
|
* user-facing superset that adds the ergonomic helpers (`remember`, `pull`, `has`) on top. Every
|
|
183
|
-
* method is async so a store may be backed by I/O, and TTLs are expressed in **seconds
|
|
184
|
-
* unit). Values are generic over `unknown`.
|
|
182
|
+
* method is async so a store may be backed by I/O, and TTLs are expressed in **seconds**. Values are generic over `unknown`.
|
|
185
183
|
*/
|
|
186
184
|
/**
|
|
187
|
-
* The cache store
|
|
185
|
+
* The cache store. The minimal persistence
|
|
188
186
|
* surface every backend implements; the {@link CacheRepository} is layered over it.
|
|
189
187
|
*/
|
|
190
188
|
interface CacheStore {
|
|
@@ -200,8 +198,7 @@ interface CacheStore {
|
|
|
200
198
|
flush(): Promise<boolean>;
|
|
201
199
|
}
|
|
202
200
|
/**
|
|
203
|
-
* The cache repository
|
|
204
|
-
* facade surface. A superset of {@link CacheStore} adding the compute-on-miss `remember` family,
|
|
201
|
+
* The cache repository. A superset of {@link CacheStore} adding the compute-on-miss `remember` family,
|
|
205
202
|
* the read-and-delete `pull`, and existence/atomic-counter helpers.
|
|
206
203
|
*/
|
|
207
204
|
interface CacheRepository extends CacheStore {
|
|
@@ -222,19 +219,17 @@ interface CacheRepository extends CacheStore {
|
|
|
222
219
|
}
|
|
223
220
|
|
|
224
221
|
/**
|
|
225
|
-
* Queue contracts — the
|
|
226
|
-
* interfaces. {@link ShouldQueue} is the marker that opts work into the queue; {@link QueueJob} is
|
|
222
|
+
* Queue contracts — the queueing and job interfaces. {@link ShouldQueue} is the marker that opts work into the queue; {@link QueueJob} is
|
|
227
223
|
* the unit of deferred work whose `handle()` a driver runs; {@link JobMiddleware} wraps that call
|
|
228
224
|
* with cross-cutting concerns. {@link Queueable} is the alias used where a queueable job is expected.
|
|
229
225
|
*/
|
|
230
226
|
/**
|
|
231
|
-
* Marker that a class should be dispatched onto a queue rather than run inline
|
|
232
|
-
* `Illuminate\Contracts\Queue\ShouldQueue` equivalent. Intentionally empty: it tags intent only.
|
|
227
|
+
* Marker that a class should be dispatched onto a queue rather than run inline. Intentionally empty: it tags intent only.
|
|
233
228
|
*/
|
|
234
229
|
interface ShouldQueue {
|
|
235
230
|
}
|
|
236
231
|
/**
|
|
237
|
-
* The unit of deferred work — the `ShouldQueue`
|
|
232
|
+
* The unit of deferred work — the `ShouldQueue` +. A driver
|
|
238
233
|
* `await`s {@link QueueJob.handle}; an optional {@link QueueJob.tries} bounds attempts before the
|
|
239
234
|
* job is treated as failed, and {@link QueueJob.middleware} wraps the call to `handle`.
|
|
240
235
|
*/
|
|
@@ -249,21 +244,21 @@ interface QueueJob {
|
|
|
249
244
|
/** Alias of {@link QueueJob} — used where a queueable job is expected (the `Queueable` concept). */
|
|
250
245
|
type Queueable = QueueJob;
|
|
251
246
|
/**
|
|
252
|
-
* One link in a job's middleware pipeline — the
|
|
247
|
+
* One link in a job's middleware pipeline — the job-middleware (`handle($job, $next)`)
|
|
253
248
|
* equivalent, expressed as a function. Awaiting `next()` runs the rest of the pipeline (and
|
|
254
249
|
* ultimately `handle`); skipping it short-circuits the job.
|
|
255
250
|
*/
|
|
256
251
|
type JobMiddleware = (job: QueueJob, next: () => Promise<void>) => Promise<void> | void;
|
|
257
252
|
|
|
258
253
|
/**
|
|
259
|
-
* Mail contracts — the
|
|
254
|
+
* Mail contracts — the interfaces. A {@link MailableContract}
|
|
260
255
|
* is a self-describing email that configures itself via `build()` and can `render()` itself; a
|
|
261
256
|
* {@link Mailer} dispatches one through whatever transport backs it. Kept transport-agnostic so the
|
|
262
257
|
* sender never cares which delivery mechanism is wired up.
|
|
263
258
|
*/
|
|
264
259
|
|
|
265
260
|
/**
|
|
266
|
-
* A self-describing email
|
|
261
|
+
* A self-describing email. {@link
|
|
267
262
|
* MailableContract.build} configures the message (recipients, subject, body) before it is sent;
|
|
268
263
|
* {@link Renderable.render} produces its rendered form for previewing or inlining.
|
|
269
264
|
*/
|
|
@@ -272,7 +267,7 @@ interface MailableContract extends Renderable {
|
|
|
272
267
|
build(): void;
|
|
273
268
|
}
|
|
274
269
|
/**
|
|
275
|
-
* The mailer
|
|
270
|
+
* The mailer contract.
|
|
276
271
|
* {@link Mailer.send} runs a mailable's lifecycle and dispatches it through the bound transport.
|
|
277
272
|
*/
|
|
278
273
|
interface Mailer {
|
|
@@ -281,14 +276,14 @@ interface Mailer {
|
|
|
281
276
|
}
|
|
282
277
|
|
|
283
278
|
/**
|
|
284
|
-
* Filesystem contract
|
|
279
|
+
* Filesystem contract. A
|
|
285
280
|
* {@link Disk} is a single named storage location (local directory, in-memory tree, cloud bucket)
|
|
286
281
|
* exposed as a uniform async API, so the layer above never cares which driver backs it. This is the
|
|
287
282
|
* common read/write/exists/delete/list subset; concrete disks may offer more. Paths are POSIX-style
|
|
288
283
|
* and relative to the disk root.
|
|
289
284
|
*/
|
|
290
285
|
/**
|
|
291
|
-
* The core filesystem surface — the common subset of
|
|
286
|
+
* The core filesystem surface — the common subset of what filesystems share.
|
|
292
287
|
* Every method is async so a driver may be backed by network or disk I/O.
|
|
293
288
|
*/
|
|
294
289
|
interface Disk {
|
|
@@ -305,7 +300,7 @@ interface Disk {
|
|
|
305
300
|
}
|
|
306
301
|
|
|
307
302
|
/**
|
|
308
|
-
* Container contract
|
|
303
|
+
* Container contract. A
|
|
309
304
|
* {@link Container} resolves dependencies by identifier (a string/symbol token or a class
|
|
310
305
|
* constructor): {@link Container.bind} registers a factory, {@link Container.singleton} registers a
|
|
311
306
|
* shared one, {@link Container.make} resolves it, and {@link Container.bound} reports registration.
|
|
@@ -319,7 +314,7 @@ type Newable<T = unknown> = new (...args: any[]) => T;
|
|
|
319
314
|
/** A thing that can identify a binding: a string/symbol token or a class constructor. */
|
|
320
315
|
type Identifier<T = unknown> = string | symbol | Newable<T>;
|
|
321
316
|
/**
|
|
322
|
-
* The service container
|
|
317
|
+
* The service container. The minimal
|
|
323
318
|
* bind/resolve surface application code holds; concrete containers add aliasing, tagging, and
|
|
324
319
|
* contextual binding on top.
|
|
325
320
|
*/
|
|
@@ -335,7 +330,7 @@ interface Container {
|
|
|
335
330
|
}
|
|
336
331
|
|
|
337
332
|
/**
|
|
338
|
-
* Cast contracts
|
|
333
|
+
* Cast contracts.
|
|
339
334
|
* A {@link Cast} transforms an attribute between its database-shaped value and its in-memory
|
|
340
335
|
* representation on read/write; {@link CastEncrypter} is the minimal encrypt/decrypt surface an
|
|
341
336
|
* encrypting cast needs. The owning model is passed as `unknown` to keep this package decoupled.
|
|
@@ -363,13 +358,13 @@ interface CastEncrypter {
|
|
|
363
358
|
}
|
|
364
359
|
|
|
365
360
|
/**
|
|
366
|
-
* `@plinthjs/contracts` — the interface-only foundation
|
|
361
|
+
* `@plinthjs/contracts` — the interface-only foundation. This
|
|
367
362
|
* package is zero-runtime and dependency-free: it exports the structural interfaces and type aliases
|
|
368
|
-
* other
|
|
363
|
+
* other Plinth packages depend on to decouple from one another. The only runtime export is
|
|
369
364
|
* {@link VERSION}.
|
|
370
365
|
*/
|
|
371
366
|
|
|
372
|
-
/** The
|
|
367
|
+
/** The Plinth version this build of `contracts` ships with. */
|
|
373
368
|
declare const VERSION = "0.1.0";
|
|
374
369
|
|
|
375
370
|
export { type Arrayable, type Authenticatable, type CacheRepository, type CacheStore, type Cast, type CastEncrypter, type Container, type Credentials, type Disk, type Encrypter, type Guard, type HasErrorBag, type HasHttpStatus, type HashOptions, type Hasher, type Identifier, type JobMiddleware, type Jsonable, type MailableContract, type Mailer, type Newable, type Objectable, type QueueJob, type Queueable, type Rememberable, type Renderable, type ShouldQueue, type StatefulGuard, type UserProvider, VERSION };
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AA2BO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["/**\n * `@plinthjs/contracts` — the interface-only foundation
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AA2BO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["/**\n * `@plinthjs/contracts` — the interface-only foundation. This\n * package is zero-runtime and dependency-free: it exports the structural interfaces and type aliases\n * other Plinth packages depend on to decouple from one another. The only runtime export is\n * {@link VERSION}.\n */\n\nexport type { Arrayable, Jsonable, Objectable, Renderable } from './support'\nexport type { HasErrorBag, HasHttpStatus } from './http'\nexport type { HashOptions, Hasher } from './hashing'\nexport type { Encrypter } from './encryption'\nexport type {\n Authenticatable,\n Credentials,\n Guard,\n Rememberable,\n StatefulGuard,\n UserProvider,\n} from './auth'\nexport type { CacheRepository, CacheStore } from './cache'\nexport type { JobMiddleware, Queueable, QueueJob, ShouldQueue } from './queue'\nexport type { Mailer, MailableContract } from './mail'\nexport type { Disk } from './filesystem'\nexport type { Container, Identifier, Newable } from './container'\nexport type { Cast, CastEncrypter } from './casts'\n\n/** The Plinth version this build of `contracts` ships with. */\nexport const VERSION = '0.1.0'\n"]}
|
package/package.json
CHANGED
|
@@ -1,10 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@plinthjs/contracts",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Plinth contracts: the interface-only foundation.",
|
|
5
5
|
"keywords": [
|
|
6
|
-
"
|
|
7
|
-
"laravel",
|
|
6
|
+
"plinth",
|
|
8
7
|
"framework",
|
|
9
8
|
"typescript",
|
|
10
9
|
"contracts"
|