@plinthjs/contracts 0.1.0 → 0.1.2

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 The Mason contributors
3
+ Copyright (c) 2026 The Plinth contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @plinthjs/contracts
2
2
 
3
- Mason's interface-only foundation, the `Illuminate\Contracts` equivalent. It exports the structural
4
- interfaces and type aliases that the other Mason packages depend on, so they can stay decoupled from
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
@@ -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, the `Illuminate\\Contracts` equivalent. This\n * package is zero-runtime and dependency-free: it exports the structural interfaces and type aliases\n * other Mason 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 Mason version this build of `contracts` ships with. */\nexport const VERSION = '0.1.0'\n"]}
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 Laravel `Illuminate\Contracts\Support` interfaces. These tiny,
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 — the `Illuminate\Contracts\Support\Arrayable` equivalent.
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 `Illuminate\Contracts\Support\Arrayable`
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 `Illuminate\Contracts\Support\Jsonable`
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 `Illuminate\Contracts\Support\Renderable`
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 {
@@ -38,13 +38,13 @@ interface Renderable {
38
38
  }
39
39
 
40
40
  /**
41
- * HTTP-renderable error contracts — the structural seams the HTTP `ExceptionHandler` reads to
41
+ * HTTP-renderable error contracts - the structural seams the HTTP `ExceptionHandler` reads to
42
42
  * render a thrown error without coupling `@plinthjs/http` to the package that threw it. An error may
43
43
  * carry an HTTP status ({@link HasHttpStatus}), a field/messages bag ({@link HasErrorBag}), or
44
44
  * both; the two are kept separate so each can be implemented independently.
45
45
  */
46
46
  /**
47
- * An error carrying the HTTP status it should render as — the seam the handler reads so a
47
+ * An error carrying the HTTP status it should render as - the seam the handler reads so a
48
48
  * validation `422` or authorization `403` renders correctly without a direct dependency.
49
49
  */
50
50
  interface HasHttpStatus {
@@ -52,8 +52,8 @@ interface HasHttpStatus {
52
52
  readonly status: number;
53
53
  }
54
54
  /**
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 Laravel's `MessageBag`-shaped error output.
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 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 — the Laravel `Illuminate\Contracts\Hashing\Hasher` equivalent. A {@link Hasher}
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 — the Laravel hashing `options` array equivalent. Expressed openly
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 — the `Illuminate\Contracts\Hashing\Hasher` equivalent and the `Hash` facade
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 — the Laravel `Illuminate\Contracts\Encryption\Encrypter` equivalent. An
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 — the `Illuminate\Contracts\Encryption\Encrypter` equivalent and the `Crypt` facade
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 Laravel `Illuminate\Contracts\Auth` interfaces.
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 — the `Illuminate\Contracts\Auth\Authenticatable` equivalent. */
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 }`. The Laravel credentials array equivalent. */
119
+ /** Login credentials - typically `{ email, password }`. */
120
120
  type Credentials = Record<string, unknown>;
121
121
  /**
122
- * A user that supports "remember me" persistence — the Laravel remember-token methods on
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 `Illuminate\Contracts\Auth\UserProvider`
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 — the `Illuminate\Contracts\Auth\Guard` equivalent. */
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 — the
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 Laravel `Illuminate\Contracts\Cache` interfaces. {@link CacheStore} is 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** (Laravel's
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 — the `Illuminate\Contracts\Cache\Store` equivalent. The minimal persistence
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 — the `Illuminate\Contracts\Cache\Repository` equivalent and the `Cache`
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,48 +219,46 @@ interface CacheRepository extends CacheStore {
222
219
  }
223
220
 
224
221
  /**
225
- * Queue contracts — the Laravel `Illuminate\Contracts\Queue` + `Illuminate\Bus\Queueable`
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 — the
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` + `Illuminate\Bus\Queueable` equivalent. A driver
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
  */
241
236
  interface QueueJob {
242
- /** Run the job's work. The `handle()` equivalent — may be sync or async; drivers always await it. */
237
+ /** Run the job's work. The `handle()` equivalent - may be sync or async; drivers always await it. */
243
238
  handle(): Promise<void> | void;
244
- /** Maximum number of attempts before the job is treated as failed — the `$tries` equivalent. */
239
+ /** Maximum number of attempts before the job is treated as failed - the `$tries` equivalent. */
245
240
  tries?: number;
246
241
  /** Return the middleware pipeline that wraps {@link QueueJob.handle}. The `middleware()` equivalent. */
247
242
  middleware?(): JobMiddleware[];
248
243
  }
249
- /** Alias of {@link QueueJob} — used where a queueable job is expected (the `Queueable` concept). */
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 Laravel job-middleware (`handle($job, $next)`)
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 Laravel `Illuminate\Contracts\Mail` interfaces. A {@link MailableContract}
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 — the `Illuminate\Contracts\Mail\Mailable` equivalent. {@link
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 — the `Illuminate\Contracts\Mail\Mailer` equivalent and the `Mail` facade surface.
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 — the Laravel `Illuminate\Contracts\Filesystem\Filesystem` equivalent. A
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 `Illuminate\Contracts\Filesystem\Filesystem`.
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,28 +300,28 @@ interface Disk {
305
300
  }
306
301
 
307
302
  /**
308
- * Container contract — the Laravel `Illuminate\Contracts\Container\Container` equivalent. A
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.
312
307
  * JS has no reflection-based autowiring, so dependencies are wired via factory functions.
313
308
  */
314
309
  /**
315
- * A class constructor — the seam a container can `new` directly. The constructor signature is
310
+ * A class constructor - the seam a container can `new` directly. The constructor signature is
316
311
  * intentionally open so any class is assignable.
317
312
  */
318
313
  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 — the `Illuminate\Contracts\Container\Container` equivalent. The minimal
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
  */
326
321
  interface Container {
327
322
  /** Register a binding from an identifier to a factory or constructable class. The `bind` equivalent. */
328
323
  bind<T>(token: Identifier<T>, concrete?: Newable<T>): void;
329
- /** Register a shared (singleton) binding — resolved once, then cached. The `singleton` equivalent. */
324
+ /** Register a shared (singleton) binding - resolved once, then cached. The `singleton` equivalent. */
330
325
  singleton<T>(token: Identifier<T>, concrete?: Newable<T>): void;
331
326
  /** Resolve an identifier to a concrete value. The `make` equivalent. */
332
327
  make<T>(token: Identifier<T>): T;
@@ -335,13 +330,13 @@ interface Container {
335
330
  }
336
331
 
337
332
  /**
338
- * Cast contracts — the Laravel `Illuminate\Contracts\Database\Eloquent\CastsAttributes` equivalent.
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.
342
337
  */
343
338
  /**
344
- * A custom attribute cast — the `CastsAttributes` equivalent. {@link Cast.get} runs on read,
339
+ * A custom attribute cast - the `CastsAttributes` equivalent. {@link Cast.get} runs on read,
345
340
  * {@link Cast.set} on write. The `model` is the owning record, typed `unknown` so this contract
346
341
  * stays free of any ORM dependency.
347
342
  */
@@ -352,7 +347,7 @@ interface Cast {
352
347
  set(value: unknown, model: unknown): unknown;
353
348
  }
354
349
  /**
355
- * The minimal encrypt/decrypt surface an encrypting cast needs — a structural subset of the
350
+ * The minimal encrypt/decrypt surface an encrypting cast needs - a structural subset of the
356
351
  * encryption `Encrypter`. Kept here so a cast can depend on it without importing the encrypter type.
357
352
  */
358
353
  interface CastEncrypter {
@@ -363,13 +358,13 @@ interface CastEncrypter {
363
358
  }
364
359
 
365
360
  /**
366
- * `@plinthjs/contracts` — the interface-only foundation, the `Illuminate\Contracts` equivalent. This
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 Mason packages depend on to decouple from one another. The only runtime export is
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 Mason version this build of `contracts` ships with. */
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 Laravel `Illuminate\Contracts\Support` interfaces. These tiny,
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 — the `Illuminate\Contracts\Support\Arrayable` equivalent.
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 `Illuminate\Contracts\Support\Arrayable`
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 `Illuminate\Contracts\Support\Jsonable`
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 `Illuminate\Contracts\Support\Renderable`
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 {
@@ -38,13 +38,13 @@ interface Renderable {
38
38
  }
39
39
 
40
40
  /**
41
- * HTTP-renderable error contracts — the structural seams the HTTP `ExceptionHandler` reads to
41
+ * HTTP-renderable error contracts - the structural seams the HTTP `ExceptionHandler` reads to
42
42
  * render a thrown error without coupling `@plinthjs/http` to the package that threw it. An error may
43
43
  * carry an HTTP status ({@link HasHttpStatus}), a field/messages bag ({@link HasErrorBag}), or
44
44
  * both; the two are kept separate so each can be implemented independently.
45
45
  */
46
46
  /**
47
- * An error carrying the HTTP status it should render as — the seam the handler reads so a
47
+ * An error carrying the HTTP status it should render as - the seam the handler reads so a
48
48
  * validation `422` or authorization `403` renders correctly without a direct dependency.
49
49
  */
50
50
  interface HasHttpStatus {
@@ -52,8 +52,8 @@ interface HasHttpStatus {
52
52
  readonly status: number;
53
53
  }
54
54
  /**
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 Laravel's `MessageBag`-shaped error output.
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 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 — the Laravel `Illuminate\Contracts\Hashing\Hasher` equivalent. A {@link Hasher}
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 — the Laravel hashing `options` array equivalent. Expressed openly
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 — the `Illuminate\Contracts\Hashing\Hasher` equivalent and the `Hash` facade
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 — the Laravel `Illuminate\Contracts\Encryption\Encrypter` equivalent. An
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 — the `Illuminate\Contracts\Encryption\Encrypter` equivalent and the `Crypt` facade
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 Laravel `Illuminate\Contracts\Auth` interfaces.
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 — the `Illuminate\Contracts\Auth\Authenticatable` equivalent. */
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 }`. The Laravel credentials array equivalent. */
119
+ /** Login credentials - typically `{ email, password }`. */
120
120
  type Credentials = Record<string, unknown>;
121
121
  /**
122
- * A user that supports "remember me" persistence — the Laravel remember-token methods on
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 `Illuminate\Contracts\Auth\UserProvider`
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 — the `Illuminate\Contracts\Auth\Guard` equivalent. */
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 — the
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 Laravel `Illuminate\Contracts\Cache` interfaces. {@link CacheStore} is 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** (Laravel's
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 — the `Illuminate\Contracts\Cache\Store` equivalent. The minimal persistence
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 — the `Illuminate\Contracts\Cache\Repository` equivalent and the `Cache`
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,48 +219,46 @@ interface CacheRepository extends CacheStore {
222
219
  }
223
220
 
224
221
  /**
225
- * Queue contracts — the Laravel `Illuminate\Contracts\Queue` + `Illuminate\Bus\Queueable`
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 — the
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` + `Illuminate\Bus\Queueable` equivalent. A driver
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
  */
241
236
  interface QueueJob {
242
- /** Run the job's work. The `handle()` equivalent — may be sync or async; drivers always await it. */
237
+ /** Run the job's work. The `handle()` equivalent - may be sync or async; drivers always await it. */
243
238
  handle(): Promise<void> | void;
244
- /** Maximum number of attempts before the job is treated as failed — the `$tries` equivalent. */
239
+ /** Maximum number of attempts before the job is treated as failed - the `$tries` equivalent. */
245
240
  tries?: number;
246
241
  /** Return the middleware pipeline that wraps {@link QueueJob.handle}. The `middleware()` equivalent. */
247
242
  middleware?(): JobMiddleware[];
248
243
  }
249
- /** Alias of {@link QueueJob} — used where a queueable job is expected (the `Queueable` concept). */
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 Laravel job-middleware (`handle($job, $next)`)
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 Laravel `Illuminate\Contracts\Mail` interfaces. A {@link MailableContract}
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 — the `Illuminate\Contracts\Mail\Mailable` equivalent. {@link
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 — the `Illuminate\Contracts\Mail\Mailer` equivalent and the `Mail` facade surface.
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 — the Laravel `Illuminate\Contracts\Filesystem\Filesystem` equivalent. A
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 `Illuminate\Contracts\Filesystem\Filesystem`.
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,28 +300,28 @@ interface Disk {
305
300
  }
306
301
 
307
302
  /**
308
- * Container contract — the Laravel `Illuminate\Contracts\Container\Container` equivalent. A
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.
312
307
  * JS has no reflection-based autowiring, so dependencies are wired via factory functions.
313
308
  */
314
309
  /**
315
- * A class constructor — the seam a container can `new` directly. The constructor signature is
310
+ * A class constructor - the seam a container can `new` directly. The constructor signature is
316
311
  * intentionally open so any class is assignable.
317
312
  */
318
313
  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 — the `Illuminate\Contracts\Container\Container` equivalent. The minimal
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
  */
326
321
  interface Container {
327
322
  /** Register a binding from an identifier to a factory or constructable class. The `bind` equivalent. */
328
323
  bind<T>(token: Identifier<T>, concrete?: Newable<T>): void;
329
- /** Register a shared (singleton) binding — resolved once, then cached. The `singleton` equivalent. */
324
+ /** Register a shared (singleton) binding - resolved once, then cached. The `singleton` equivalent. */
330
325
  singleton<T>(token: Identifier<T>, concrete?: Newable<T>): void;
331
326
  /** Resolve an identifier to a concrete value. The `make` equivalent. */
332
327
  make<T>(token: Identifier<T>): T;
@@ -335,13 +330,13 @@ interface Container {
335
330
  }
336
331
 
337
332
  /**
338
- * Cast contracts — the Laravel `Illuminate\Contracts\Database\Eloquent\CastsAttributes` equivalent.
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.
342
337
  */
343
338
  /**
344
- * A custom attribute cast — the `CastsAttributes` equivalent. {@link Cast.get} runs on read,
339
+ * A custom attribute cast - the `CastsAttributes` equivalent. {@link Cast.get} runs on read,
345
340
  * {@link Cast.set} on write. The `model` is the owning record, typed `unknown` so this contract
346
341
  * stays free of any ORM dependency.
347
342
  */
@@ -352,7 +347,7 @@ interface Cast {
352
347
  set(value: unknown, model: unknown): unknown;
353
348
  }
354
349
  /**
355
- * The minimal encrypt/decrypt surface an encrypting cast needs — a structural subset of the
350
+ * The minimal encrypt/decrypt surface an encrypting cast needs - a structural subset of the
356
351
  * encryption `Encrypter`. Kept here so a cast can depend on it without importing the encrypter type.
357
352
  */
358
353
  interface CastEncrypter {
@@ -363,13 +358,13 @@ interface CastEncrypter {
363
358
  }
364
359
 
365
360
  /**
366
- * `@plinthjs/contracts` — the interface-only foundation, the `Illuminate\Contracts` equivalent. This
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 Mason packages depend on to decouple from one another. The only runtime export is
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 Mason version this build of `contracts` ships with. */
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, the `Illuminate\\Contracts` equivalent. This\n * package is zero-runtime and dependency-free: it exports the structural interfaces and type aliases\n * other Mason 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 Mason version this build of `contracts` ships with. */\nexport const VERSION = '0.1.0'\n"]}
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,21 +1,20 @@
1
1
  {
2
2
  "name": "@plinthjs/contracts",
3
- "version": "0.1.0",
4
- "description": "Mason contracts: the interface-only foundation (the Illuminate\\Contracts equivalent).",
3
+ "version": "0.1.2",
4
+ "description": "Plinth contracts: the interface-only foundation.",
5
5
  "keywords": [
6
- "mason",
7
- "laravel",
6
+ "plinth",
8
7
  "framework",
9
8
  "typescript",
10
9
  "contracts"
11
10
  ],
12
- "homepage": "https://github.com/anilkumarthakur60/js-framework/tree/main/packages/contracts#readme",
11
+ "homepage": "https://github.com/anilkumarthakur60/plinthjs/tree/main/packages/contracts#readme",
13
12
  "bugs": {
14
- "url": "https://github.com/anilkumarthakur60/js-framework/issues"
13
+ "url": "https://github.com/anilkumarthakur60/plinthjs/issues"
15
14
  },
16
15
  "repository": {
17
16
  "type": "git",
18
- "url": "git+https://github.com/anilkumarthakur60/js-framework.git",
17
+ "url": "git+https://github.com/anilkumarthakur60/plinthjs.git",
19
18
  "directory": "packages/contracts"
20
19
  },
21
20
  "license": "MIT",