@plinthjs/contracts 0.0.0-stage → 0.1.0
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 +21 -0
- package/README.md +93 -2
- package/dist/index.cjs +8 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +375 -0
- package/dist/index.d.ts +375 -0
- package/dist/index.js +6 -0
- package/dist/index.js.map +1 -0
- package/package.json +55 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 The Mason contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,94 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @plinthjs/contracts
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
5
|
+
one another. The package is zero-runtime and dependency-free: the only value it exports is `VERSION`.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install @plinthjs/contracts
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
Depend on a contract instead of a concrete implementation. Because the interfaces are structural,
|
|
16
|
+
any object with the right shape satisfies them, with no base class to extend.
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import type { CacheRepository, Hasher } from '@plinthjs/contracts'
|
|
20
|
+
|
|
21
|
+
export class ReportService {
|
|
22
|
+
constructor(private readonly cache: CacheRepository) {}
|
|
23
|
+
|
|
24
|
+
async summary(): Promise<string> {
|
|
25
|
+
return this.cache.remember('report:summary', 300, async () => buildSummary())
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
// A tiny hasher for tests, satisfying the contract structurally.
|
|
30
|
+
const plainHasher: Hasher = {
|
|
31
|
+
make: (value) => `plain:${value}`,
|
|
32
|
+
check: (value, hash) => hash === `plain:${value}`,
|
|
33
|
+
needsRehash: () => false,
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## What is included
|
|
38
|
+
|
|
39
|
+
| Area | Contracts |
|
|
40
|
+
| ---------- | ------------------------------------------------------------------------------------------ |
|
|
41
|
+
| Support | `Arrayable`, `Objectable`, `Jsonable`, `Renderable` |
|
|
42
|
+
| HTTP | `HasHttpStatus`, `HasErrorBag` |
|
|
43
|
+
| Hashing | `Hasher`, `HashOptions` |
|
|
44
|
+
| Encryption | `Encrypter` |
|
|
45
|
+
| Auth | `Authenticatable`, `Credentials`, `Rememberable`, `UserProvider`, `Guard`, `StatefulGuard` |
|
|
46
|
+
| Cache | `CacheStore`, `CacheRepository` |
|
|
47
|
+
| Queue | `ShouldQueue`, `QueueJob`, `Queueable`, `JobMiddleware` |
|
|
48
|
+
| Mail | `Mailer`, `MailableContract` |
|
|
49
|
+
| Filesystem | `Disk` |
|
|
50
|
+
| Container | `Container`, `Identifier`, `Newable` |
|
|
51
|
+
| Casts | `Cast`, `CastEncrypter` |
|
|
52
|
+
|
|
53
|
+
## Examples
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
import type {
|
|
57
|
+
Authenticatable,
|
|
58
|
+
HasErrorBag,
|
|
59
|
+
HasHttpStatus,
|
|
60
|
+
JobMiddleware,
|
|
61
|
+
QueueJob,
|
|
62
|
+
} from '@plinthjs/contracts'
|
|
63
|
+
|
|
64
|
+
// An error that the HTTP layer can map to a 422 with a field bag.
|
|
65
|
+
class FormError extends Error implements HasHttpStatus, HasErrorBag {
|
|
66
|
+
readonly status = 422
|
|
67
|
+
constructor(readonly errors: Record<string, string[]>) {
|
|
68
|
+
super('The given data was invalid.')
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
// A user record the auth layer can work with.
|
|
73
|
+
const user: Authenticatable = {
|
|
74
|
+
getAuthIdentifier: () => 1,
|
|
75
|
+
getAuthIdentifierName: () => 'id',
|
|
76
|
+
getAuthPassword: () => '$2b$10$...',
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// A queued job with per-job middleware.
|
|
80
|
+
const logTiming: JobMiddleware = async (job, next) => {
|
|
81
|
+
const started = Date.now()
|
|
82
|
+
await next()
|
|
83
|
+
console.log(`job took ${Date.now() - started}ms`)
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const job: QueueJob = {
|
|
87
|
+
tries: 3,
|
|
88
|
+
handle: async () => sendWelcomeEmail(),
|
|
89
|
+
middleware: () => [logTiming],
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
All exports other than `VERSION` are `type`-only, so importing them with `import type` adds nothing
|
|
94
|
+
to your bundle.
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +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"]}
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Core support contracts — the Laravel `Illuminate\Contracts\Support` interfaces. These tiny,
|
|
3
|
+
* structural shapes let any value advertise that it can be turned into an array
|
|
4
|
+
* ({@link Arrayable}), serialized to JSON ({@link Jsonable}), or rendered to a string
|
|
5
|
+
* ({@link Renderable}) without coupling the consumer to a concrete type.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* A value convertible to an array — the `Illuminate\Contracts\Support\Arrayable` equivalent.
|
|
9
|
+
* Generic over the element type so `Arrayable<User>` yields `User[]`.
|
|
10
|
+
*/
|
|
11
|
+
interface Arrayable<T = unknown> {
|
|
12
|
+
/** Return the value as a plain array. The `toArray()` equivalent. */
|
|
13
|
+
toArray(): T[];
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* A value convertible to a plain keyed object — the `Illuminate\Contracts\Support\Arrayable`
|
|
17
|
+
* object-shaped variant, for things that flatten to a record rather than a list.
|
|
18
|
+
*/
|
|
19
|
+
interface Objectable<T = unknown> {
|
|
20
|
+
/** Return the value as a plain keyed object. */
|
|
21
|
+
toObject(): Record<string, T>;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* A value convertible to a JSON-safe representation — the `Illuminate\Contracts\Support\Jsonable`
|
|
25
|
+
* equivalent. Returns the value to be serialized (not the JSON string) so callers control encoding.
|
|
26
|
+
*/
|
|
27
|
+
interface Jsonable {
|
|
28
|
+
/** Return the JSON-safe representation of this value. The `toJson()` equivalent. */
|
|
29
|
+
toJSON(): unknown;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* A value that can render itself to a string — the `Illuminate\Contracts\Support\Renderable`
|
|
33
|
+
* equivalent (e.g. a view or a mailable preview).
|
|
34
|
+
*/
|
|
35
|
+
interface Renderable {
|
|
36
|
+
/** Render this value to a string. The `render()` equivalent. */
|
|
37
|
+
render(): string;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* HTTP-renderable error contracts — the structural seams the HTTP `ExceptionHandler` reads to
|
|
42
|
+
* render a thrown error without coupling `@plinthjs/http` to the package that threw it. An error may
|
|
43
|
+
* carry an HTTP status ({@link HasHttpStatus}), a field/messages bag ({@link HasErrorBag}), or
|
|
44
|
+
* both; the two are kept separate so each can be implemented independently.
|
|
45
|
+
*/
|
|
46
|
+
/**
|
|
47
|
+
* An error carrying the HTTP status it should render as — the seam the handler reads so a
|
|
48
|
+
* validation `422` or authorization `403` renders correctly without a direct dependency.
|
|
49
|
+
*/
|
|
50
|
+
interface HasHttpStatus {
|
|
51
|
+
/** The HTTP status code this error renders as, e.g. `403`, `404`, `422`. */
|
|
52
|
+
readonly status: number;
|
|
53
|
+
}
|
|
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.
|
|
57
|
+
*/
|
|
58
|
+
interface HasErrorBag {
|
|
59
|
+
/** Validation/field errors keyed by field name, each a list of human-readable messages. */
|
|
60
|
+
readonly errors: Record<string, string[]>;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Hashing contract — the Laravel `Illuminate\Contracts\Hashing\Hasher` equivalent. A {@link Hasher}
|
|
65
|
+
* hashes secrets (passwords) one-way, verifies a candidate against a stored hash in constant time,
|
|
66
|
+
* and reports when a stored hash should be recomputed because its cost parameters have changed.
|
|
67
|
+
*/
|
|
68
|
+
/**
|
|
69
|
+
* Tunable hashing cost options — the Laravel hashing `options` array equivalent. Expressed openly
|
|
70
|
+
* as a record so each driver (bcrypt, argon, scrypt) can accept its own cost knobs.
|
|
71
|
+
*/
|
|
72
|
+
type HashOptions = Record<string, unknown>;
|
|
73
|
+
/**
|
|
74
|
+
* The password hasher — the `Illuminate\Contracts\Hashing\Hasher` equivalent and the `Hash` facade
|
|
75
|
+
* surface. Implementations are expected to use a self-describing hash format so parameters can be
|
|
76
|
+
* detected by {@link Hasher.needsRehash} and evolve over time.
|
|
77
|
+
*/
|
|
78
|
+
interface Hasher {
|
|
79
|
+
/** Hash a value one-way, returning a self-describing hash string. The `make()` equivalent. */
|
|
80
|
+
make(value: string, options?: HashOptions): string;
|
|
81
|
+
/** Verify a value against a hash in constant time. The `check()` equivalent. */
|
|
82
|
+
check(value: string, hash: string): boolean;
|
|
83
|
+
/** Whether a hash should be recomputed because its cost differs from `options`. The `needsRehash()` equivalent. */
|
|
84
|
+
needsRehash(hash: string, options?: HashOptions): boolean;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Encryption contract — the Laravel `Illuminate\Contracts\Encryption\Encrypter` equivalent. An
|
|
89
|
+
* {@link Encrypter} performs authenticated symmetric encryption: any JSON-safe value is serialized
|
|
90
|
+
* and encrypted to an opaque string by {@link Encrypter.encrypt}, and revived by
|
|
91
|
+
* {@link Encrypter.decrypt} (which is expected to throw if the payload is tampered or the key wrong).
|
|
92
|
+
*/
|
|
93
|
+
/**
|
|
94
|
+
* The encrypter — the `Illuminate\Contracts\Encryption\Encrypter` equivalent and the `Crypt` facade
|
|
95
|
+
* surface. Values round-trip through JSON, so {@link Encrypter.decrypt} returns `unknown`.
|
|
96
|
+
*/
|
|
97
|
+
interface Encrypter {
|
|
98
|
+
/** Serialize and encrypt a value into an opaque payload string. The `encrypt()` equivalent. */
|
|
99
|
+
encrypt(value: unknown): string;
|
|
100
|
+
/** Decrypt and deserialize a payload produced by {@link Encrypter.encrypt}. The `decrypt()` equivalent. */
|
|
101
|
+
decrypt(payload: string): unknown;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Authentication contracts — the Laravel `Illuminate\Contracts\Auth` interfaces.
|
|
106
|
+
* {@link Authenticatable} is a user that can be authenticated; {@link UserProvider} retrieves and
|
|
107
|
+
* validates users from storage; {@link Guard} reads who the current user is; {@link StatefulGuard}
|
|
108
|
+
* also logs them in and out across requests; {@link Rememberable} adds "remember me" persistence.
|
|
109
|
+
*/
|
|
110
|
+
/** A user that can be authenticated — the `Illuminate\Contracts\Auth\Authenticatable` equivalent. */
|
|
111
|
+
interface Authenticatable {
|
|
112
|
+
/** The unique identifier (primary key) for the user. */
|
|
113
|
+
getAuthIdentifier(): string | number;
|
|
114
|
+
/** The name of the identifier field (e.g. `id`). */
|
|
115
|
+
getAuthIdentifierName(): string;
|
|
116
|
+
/** The hashed password used to validate credentials. */
|
|
117
|
+
getAuthPassword(): string;
|
|
118
|
+
}
|
|
119
|
+
/** Login credentials — typically `{ email, password }`. The Laravel credentials array equivalent. */
|
|
120
|
+
type Credentials = Record<string, unknown>;
|
|
121
|
+
/**
|
|
122
|
+
* A user that supports "remember me" persistence — the Laravel remember-token methods on
|
|
123
|
+
* `Authenticatable`. Kept separate so a user can opt into it independently.
|
|
124
|
+
*/
|
|
125
|
+
interface Rememberable {
|
|
126
|
+
/** The persisted remember-me token, or `null` if none. */
|
|
127
|
+
getRememberToken(): string | null;
|
|
128
|
+
/** Persist (in memory) a new remember-me token. */
|
|
129
|
+
setRememberToken(token: string): void;
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Retrieves and validates users from storage — the `Illuminate\Contracts\Auth\UserProvider`
|
|
133
|
+
* equivalent. The seam between a guard and however users are persisted.
|
|
134
|
+
*/
|
|
135
|
+
interface UserProvider {
|
|
136
|
+
/** Find a user by primary key, or `null`. */
|
|
137
|
+
retrieveById(identifier: string | number): Promise<Authenticatable | null>;
|
|
138
|
+
/** Find a user by primary key whose remember-me token matches, or `null` (constant-time). */
|
|
139
|
+
retrieveByToken(identifier: string | number, token: string): Promise<Authenticatable | null>;
|
|
140
|
+
/** Persist a new remember-me token for `user`. */
|
|
141
|
+
updateRememberToken(user: Authenticatable, token: string): Promise<void>;
|
|
142
|
+
/** Find a user matching the non-password credentials, or `null`. */
|
|
143
|
+
retrieveByCredentials(credentials: Credentials): Promise<Authenticatable | null>;
|
|
144
|
+
/** Whether `credentials` validate against `user` (constant-time password check). */
|
|
145
|
+
validateCredentials(user: Authenticatable, credentials: Credentials): Promise<boolean>;
|
|
146
|
+
}
|
|
147
|
+
/** A read-only authentication guard — the `Illuminate\Contracts\Auth\Guard` equivalent. */
|
|
148
|
+
interface Guard {
|
|
149
|
+
/** Whether a user is authenticated. */
|
|
150
|
+
check(): Promise<boolean>;
|
|
151
|
+
/** Whether no user is authenticated. */
|
|
152
|
+
guest(): Promise<boolean>;
|
|
153
|
+
/** The authenticated user, or `null`. */
|
|
154
|
+
user(): Promise<Authenticatable | null>;
|
|
155
|
+
/** The authenticated user's identifier, or `null`. */
|
|
156
|
+
id(): Promise<string | number | null>;
|
|
157
|
+
/** Whether the credentials are valid, without logging anyone in. */
|
|
158
|
+
validate(credentials: Credentials): Promise<boolean>;
|
|
159
|
+
/** Set the current user explicitly (e.g. after registration). */
|
|
160
|
+
setUser(user: Authenticatable): void;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* A guard that can also log users in and out across requests — the
|
|
164
|
+
* `Illuminate\Contracts\Auth\StatefulGuard` equivalent.
|
|
165
|
+
*/
|
|
166
|
+
interface StatefulGuard extends Guard {
|
|
167
|
+
/** Validate credentials and, on success, log the user in. */
|
|
168
|
+
attempt(credentials: Credentials): Promise<boolean>;
|
|
169
|
+
/** Validate credentials and set the user for this request only (no persistence). */
|
|
170
|
+
once(credentials: Credentials): Promise<boolean>;
|
|
171
|
+
/** Log a user in (persist their id). */
|
|
172
|
+
login(user: Authenticatable): void;
|
|
173
|
+
/** Log in by identifier, returning the user (or `null` if unknown). */
|
|
174
|
+
loginUsingId(id: string | number): Promise<Authenticatable | null>;
|
|
175
|
+
/** Log the current user out. */
|
|
176
|
+
logout(): void;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Cache contracts — the Laravel `Illuminate\Contracts\Cache` interfaces. {@link CacheStore} is the
|
|
181
|
+
* lowest layer (the swappable backend: array, file, Redis); {@link CacheRepository} is the
|
|
182
|
+
* 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`.
|
|
185
|
+
*/
|
|
186
|
+
/**
|
|
187
|
+
* The cache store — the `Illuminate\Contracts\Cache\Store` equivalent. The minimal persistence
|
|
188
|
+
* surface every backend implements; the {@link CacheRepository} is layered over it.
|
|
189
|
+
*/
|
|
190
|
+
interface CacheStore {
|
|
191
|
+
/** Fetch a value by key, or `null` when missing/expired. The `get` equivalent. */
|
|
192
|
+
get<T = unknown>(key: string): Promise<T | null>;
|
|
193
|
+
/** Store a value for `ttlSeconds` (or forever when omitted). The `put` equivalent. */
|
|
194
|
+
put<T>(key: string, value: T, ttlSeconds?: number): Promise<boolean>;
|
|
195
|
+
/** Store a value that never expires. The `forever` equivalent. */
|
|
196
|
+
forever<T>(key: string, value: T): Promise<boolean>;
|
|
197
|
+
/** Remove a key, returning whether it existed. The `forget` equivalent. */
|
|
198
|
+
forget(key: string): Promise<boolean>;
|
|
199
|
+
/** Remove every key. The `flush` equivalent. */
|
|
200
|
+
flush(): Promise<boolean>;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
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,
|
|
205
|
+
* the read-and-delete `pull`, and existence/atomic-counter helpers.
|
|
206
|
+
*/
|
|
207
|
+
interface CacheRepository extends CacheStore {
|
|
208
|
+
/** Whether a live value exists for the key. The `has` equivalent. */
|
|
209
|
+
has(key: string): Promise<boolean>;
|
|
210
|
+
/** Store only if absent, returning whether it was written. The `add` equivalent. */
|
|
211
|
+
add<T>(key: string, value: T, ttlSeconds?: number): Promise<boolean>;
|
|
212
|
+
/** Atomically add `by` to a numeric key, returning the new value. The `increment` equivalent. */
|
|
213
|
+
increment(key: string, by?: number): Promise<number>;
|
|
214
|
+
/** Atomically subtract `by` from a numeric key, returning the new value. The `decrement` equivalent. */
|
|
215
|
+
decrement(key: string, by?: number): Promise<number>;
|
|
216
|
+
/** Fetch a value and remove it in one shot, or `null` when missing. The `pull` equivalent. */
|
|
217
|
+
pull<T = unknown>(key: string): Promise<T | null>;
|
|
218
|
+
/** Return the cached value, or compute it via `callback`, store it for `ttlSeconds`, and return it. The `remember` equivalent. */
|
|
219
|
+
remember<T>(key: string, ttlSeconds: number, callback: () => T | Promise<T>): Promise<T>;
|
|
220
|
+
/** Like {@link CacheRepository.remember} but stores the value forever. The `rememberForever` equivalent. */
|
|
221
|
+
rememberForever<T>(key: string, callback: () => T | Promise<T>): Promise<T>;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
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
|
|
227
|
+
* the unit of deferred work whose `handle()` a driver runs; {@link JobMiddleware} wraps that call
|
|
228
|
+
* with cross-cutting concerns. {@link Queueable} is the alias used where a queueable job is expected.
|
|
229
|
+
*/
|
|
230
|
+
/**
|
|
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.
|
|
233
|
+
*/
|
|
234
|
+
interface ShouldQueue {
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* The unit of deferred work — the `ShouldQueue` + `Illuminate\Bus\Queueable` equivalent. A driver
|
|
238
|
+
* `await`s {@link QueueJob.handle}; an optional {@link QueueJob.tries} bounds attempts before the
|
|
239
|
+
* job is treated as failed, and {@link QueueJob.middleware} wraps the call to `handle`.
|
|
240
|
+
*/
|
|
241
|
+
interface QueueJob {
|
|
242
|
+
/** Run the job's work. The `handle()` equivalent — may be sync or async; drivers always await it. */
|
|
243
|
+
handle(): Promise<void> | void;
|
|
244
|
+
/** Maximum number of attempts before the job is treated as failed — the `$tries` equivalent. */
|
|
245
|
+
tries?: number;
|
|
246
|
+
/** Return the middleware pipeline that wraps {@link QueueJob.handle}. The `middleware()` equivalent. */
|
|
247
|
+
middleware?(): JobMiddleware[];
|
|
248
|
+
}
|
|
249
|
+
/** Alias of {@link QueueJob} — used where a queueable job is expected (the `Queueable` concept). */
|
|
250
|
+
type Queueable = QueueJob;
|
|
251
|
+
/**
|
|
252
|
+
* One link in a job's middleware pipeline — the Laravel job-middleware (`handle($job, $next)`)
|
|
253
|
+
* equivalent, expressed as a function. Awaiting `next()` runs the rest of the pipeline (and
|
|
254
|
+
* ultimately `handle`); skipping it short-circuits the job.
|
|
255
|
+
*/
|
|
256
|
+
type JobMiddleware = (job: QueueJob, next: () => Promise<void>) => Promise<void> | void;
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* Mail contracts — the Laravel `Illuminate\Contracts\Mail` interfaces. A {@link MailableContract}
|
|
260
|
+
* is a self-describing email that configures itself via `build()` and can `render()` itself; a
|
|
261
|
+
* {@link Mailer} dispatches one through whatever transport backs it. Kept transport-agnostic so the
|
|
262
|
+
* sender never cares which delivery mechanism is wired up.
|
|
263
|
+
*/
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* A self-describing email — the `Illuminate\Contracts\Mail\Mailable` equivalent. {@link
|
|
267
|
+
* MailableContract.build} configures the message (recipients, subject, body) before it is sent;
|
|
268
|
+
* {@link Renderable.render} produces its rendered form for previewing or inlining.
|
|
269
|
+
*/
|
|
270
|
+
interface MailableContract extends Renderable {
|
|
271
|
+
/** Configure the message before sending. The `build()` equivalent (invoked once by the mailer). */
|
|
272
|
+
build(): void;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* The mailer — the `Illuminate\Contracts\Mail\Mailer` equivalent and the `Mail` facade surface.
|
|
276
|
+
* {@link Mailer.send} runs a mailable's lifecycle and dispatches it through the bound transport.
|
|
277
|
+
*/
|
|
278
|
+
interface Mailer {
|
|
279
|
+
/** Run a mailable's lifecycle and dispatch it. The `send()` equivalent. */
|
|
280
|
+
send(mailable: MailableContract): Promise<void>;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Filesystem contract — the Laravel `Illuminate\Contracts\Filesystem\Filesystem` equivalent. A
|
|
285
|
+
* {@link Disk} is a single named storage location (local directory, in-memory tree, cloud bucket)
|
|
286
|
+
* exposed as a uniform async API, so the layer above never cares which driver backs it. This is the
|
|
287
|
+
* common read/write/exists/delete/list subset; concrete disks may offer more. Paths are POSIX-style
|
|
288
|
+
* and relative to the disk root.
|
|
289
|
+
*/
|
|
290
|
+
/**
|
|
291
|
+
* The core filesystem surface — the common subset of `Illuminate\Contracts\Filesystem\Filesystem`.
|
|
292
|
+
* Every method is async so a driver may be backed by network or disk I/O.
|
|
293
|
+
*/
|
|
294
|
+
interface Disk {
|
|
295
|
+
/** Read a file's contents as a UTF-8 string. Rejects when the file is missing. The `get` equivalent. */
|
|
296
|
+
get(path: string): Promise<string>;
|
|
297
|
+
/** Write `contents` to a file, creating parent directories as needed. The `put` equivalent. */
|
|
298
|
+
put(path: string, contents: string): Promise<boolean>;
|
|
299
|
+
/** Whether a file or directory exists at `path`. The `exists` equivalent. */
|
|
300
|
+
exists(path: string): Promise<boolean>;
|
|
301
|
+
/** Remove a file, returning `true` when it existed. The `delete` equivalent. */
|
|
302
|
+
delete(path: string): Promise<boolean>;
|
|
303
|
+
/** Relative paths of the files directly within `dir` (non-recursive). The `files` equivalent. */
|
|
304
|
+
files(dir?: string): Promise<string[]>;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Container contract — the Laravel `Illuminate\Contracts\Container\Container` equivalent. A
|
|
309
|
+
* {@link Container} resolves dependencies by identifier (a string/symbol token or a class
|
|
310
|
+
* constructor): {@link Container.bind} registers a factory, {@link Container.singleton} registers a
|
|
311
|
+
* shared one, {@link Container.make} resolves it, and {@link Container.bound} reports registration.
|
|
312
|
+
* JS has no reflection-based autowiring, so dependencies are wired via factory functions.
|
|
313
|
+
*/
|
|
314
|
+
/**
|
|
315
|
+
* A class constructor — the seam a container can `new` directly. The constructor signature is
|
|
316
|
+
* intentionally open so any class is assignable.
|
|
317
|
+
*/
|
|
318
|
+
type Newable<T = unknown> = new (...args: any[]) => T;
|
|
319
|
+
/** A thing that can identify a binding: a string/symbol token or a class constructor. */
|
|
320
|
+
type Identifier<T = unknown> = string | symbol | Newable<T>;
|
|
321
|
+
/**
|
|
322
|
+
* The service container — the `Illuminate\Contracts\Container\Container` equivalent. The minimal
|
|
323
|
+
* bind/resolve surface application code holds; concrete containers add aliasing, tagging, and
|
|
324
|
+
* contextual binding on top.
|
|
325
|
+
*/
|
|
326
|
+
interface Container {
|
|
327
|
+
/** Register a binding from an identifier to a factory or constructable class. The `bind` equivalent. */
|
|
328
|
+
bind<T>(token: Identifier<T>, concrete?: Newable<T>): void;
|
|
329
|
+
/** Register a shared (singleton) binding — resolved once, then cached. The `singleton` equivalent. */
|
|
330
|
+
singleton<T>(token: Identifier<T>, concrete?: Newable<T>): void;
|
|
331
|
+
/** Resolve an identifier to a concrete value. The `make` equivalent. */
|
|
332
|
+
make<T>(token: Identifier<T>): T;
|
|
333
|
+
/** Whether anything is registered for this identifier. The `bound` equivalent. */
|
|
334
|
+
bound(token: Identifier): boolean;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Cast contracts — the Laravel `Illuminate\Contracts\Database\Eloquent\CastsAttributes` equivalent.
|
|
339
|
+
* A {@link Cast} transforms an attribute between its database-shaped value and its in-memory
|
|
340
|
+
* representation on read/write; {@link CastEncrypter} is the minimal encrypt/decrypt surface an
|
|
341
|
+
* encrypting cast needs. The owning model is passed as `unknown` to keep this package decoupled.
|
|
342
|
+
*/
|
|
343
|
+
/**
|
|
344
|
+
* A custom attribute cast — the `CastsAttributes` equivalent. {@link Cast.get} runs on read,
|
|
345
|
+
* {@link Cast.set} on write. The `model` is the owning record, typed `unknown` so this contract
|
|
346
|
+
* stays free of any ORM dependency.
|
|
347
|
+
*/
|
|
348
|
+
interface Cast {
|
|
349
|
+
/** Transform the DB-shaped value into its in-memory representation. The `get` equivalent. */
|
|
350
|
+
get(value: unknown, model: unknown): unknown;
|
|
351
|
+
/** Transform an in-memory value back into its DB-shaped representation. The `set` equivalent. */
|
|
352
|
+
set(value: unknown, model: unknown): unknown;
|
|
353
|
+
}
|
|
354
|
+
/**
|
|
355
|
+
* The minimal encrypt/decrypt surface an encrypting cast needs — a structural subset of the
|
|
356
|
+
* encryption `Encrypter`. Kept here so a cast can depend on it without importing the encrypter type.
|
|
357
|
+
*/
|
|
358
|
+
interface CastEncrypter {
|
|
359
|
+
/** Serialize and encrypt a value into an opaque payload string. */
|
|
360
|
+
encrypt(value: unknown): string;
|
|
361
|
+
/** Decrypt and deserialize a payload produced by {@link CastEncrypter.encrypt}. */
|
|
362
|
+
decrypt(payload: string): unknown;
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
/**
|
|
366
|
+
* `@plinthjs/contracts` — the interface-only foundation, the `Illuminate\Contracts` equivalent. This
|
|
367
|
+
* 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
|
|
369
|
+
* {@link VERSION}.
|
|
370
|
+
*/
|
|
371
|
+
|
|
372
|
+
/** The Mason version this build of `contracts` ships with. */
|
|
373
|
+
declare const VERSION = "0.1.0";
|
|
374
|
+
|
|
375
|
+
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
ADDED
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Core support contracts — the Laravel `Illuminate\Contracts\Support` interfaces. These tiny,
|
|
3
|
+
* structural shapes let any value advertise that it can be turned into an array
|
|
4
|
+
* ({@link Arrayable}), serialized to JSON ({@link Jsonable}), or rendered to a string
|
|
5
|
+
* ({@link Renderable}) without coupling the consumer to a concrete type.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* A value convertible to an array — the `Illuminate\Contracts\Support\Arrayable` equivalent.
|
|
9
|
+
* Generic over the element type so `Arrayable<User>` yields `User[]`.
|
|
10
|
+
*/
|
|
11
|
+
interface Arrayable<T = unknown> {
|
|
12
|
+
/** Return the value as a plain array. The `toArray()` equivalent. */
|
|
13
|
+
toArray(): T[];
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* A value convertible to a plain keyed object — the `Illuminate\Contracts\Support\Arrayable`
|
|
17
|
+
* object-shaped variant, for things that flatten to a record rather than a list.
|
|
18
|
+
*/
|
|
19
|
+
interface Objectable<T = unknown> {
|
|
20
|
+
/** Return the value as a plain keyed object. */
|
|
21
|
+
toObject(): Record<string, T>;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* A value convertible to a JSON-safe representation — the `Illuminate\Contracts\Support\Jsonable`
|
|
25
|
+
* equivalent. Returns the value to be serialized (not the JSON string) so callers control encoding.
|
|
26
|
+
*/
|
|
27
|
+
interface Jsonable {
|
|
28
|
+
/** Return the JSON-safe representation of this value. The `toJson()` equivalent. */
|
|
29
|
+
toJSON(): unknown;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* A value that can render itself to a string — the `Illuminate\Contracts\Support\Renderable`
|
|
33
|
+
* equivalent (e.g. a view or a mailable preview).
|
|
34
|
+
*/
|
|
35
|
+
interface Renderable {
|
|
36
|
+
/** Render this value to a string. The `render()` equivalent. */
|
|
37
|
+
render(): string;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* HTTP-renderable error contracts — the structural seams the HTTP `ExceptionHandler` reads to
|
|
42
|
+
* render a thrown error without coupling `@plinthjs/http` to the package that threw it. An error may
|
|
43
|
+
* carry an HTTP status ({@link HasHttpStatus}), a field/messages bag ({@link HasErrorBag}), or
|
|
44
|
+
* both; the two are kept separate so each can be implemented independently.
|
|
45
|
+
*/
|
|
46
|
+
/**
|
|
47
|
+
* An error carrying the HTTP status it should render as — the seam the handler reads so a
|
|
48
|
+
* validation `422` or authorization `403` renders correctly without a direct dependency.
|
|
49
|
+
*/
|
|
50
|
+
interface HasHttpStatus {
|
|
51
|
+
/** The HTTP status code this error renders as, e.g. `403`, `404`, `422`. */
|
|
52
|
+
readonly status: number;
|
|
53
|
+
}
|
|
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.
|
|
57
|
+
*/
|
|
58
|
+
interface HasErrorBag {
|
|
59
|
+
/** Validation/field errors keyed by field name, each a list of human-readable messages. */
|
|
60
|
+
readonly errors: Record<string, string[]>;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Hashing contract — the Laravel `Illuminate\Contracts\Hashing\Hasher` equivalent. A {@link Hasher}
|
|
65
|
+
* hashes secrets (passwords) one-way, verifies a candidate against a stored hash in constant time,
|
|
66
|
+
* and reports when a stored hash should be recomputed because its cost parameters have changed.
|
|
67
|
+
*/
|
|
68
|
+
/**
|
|
69
|
+
* Tunable hashing cost options — the Laravel hashing `options` array equivalent. Expressed openly
|
|
70
|
+
* as a record so each driver (bcrypt, argon, scrypt) can accept its own cost knobs.
|
|
71
|
+
*/
|
|
72
|
+
type HashOptions = Record<string, unknown>;
|
|
73
|
+
/**
|
|
74
|
+
* The password hasher — the `Illuminate\Contracts\Hashing\Hasher` equivalent and the `Hash` facade
|
|
75
|
+
* surface. Implementations are expected to use a self-describing hash format so parameters can be
|
|
76
|
+
* detected by {@link Hasher.needsRehash} and evolve over time.
|
|
77
|
+
*/
|
|
78
|
+
interface Hasher {
|
|
79
|
+
/** Hash a value one-way, returning a self-describing hash string. The `make()` equivalent. */
|
|
80
|
+
make(value: string, options?: HashOptions): string;
|
|
81
|
+
/** Verify a value against a hash in constant time. The `check()` equivalent. */
|
|
82
|
+
check(value: string, hash: string): boolean;
|
|
83
|
+
/** Whether a hash should be recomputed because its cost differs from `options`. The `needsRehash()` equivalent. */
|
|
84
|
+
needsRehash(hash: string, options?: HashOptions): boolean;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Encryption contract — the Laravel `Illuminate\Contracts\Encryption\Encrypter` equivalent. An
|
|
89
|
+
* {@link Encrypter} performs authenticated symmetric encryption: any JSON-safe value is serialized
|
|
90
|
+
* and encrypted to an opaque string by {@link Encrypter.encrypt}, and revived by
|
|
91
|
+
* {@link Encrypter.decrypt} (which is expected to throw if the payload is tampered or the key wrong).
|
|
92
|
+
*/
|
|
93
|
+
/**
|
|
94
|
+
* The encrypter — the `Illuminate\Contracts\Encryption\Encrypter` equivalent and the `Crypt` facade
|
|
95
|
+
* surface. Values round-trip through JSON, so {@link Encrypter.decrypt} returns `unknown`.
|
|
96
|
+
*/
|
|
97
|
+
interface Encrypter {
|
|
98
|
+
/** Serialize and encrypt a value into an opaque payload string. The `encrypt()` equivalent. */
|
|
99
|
+
encrypt(value: unknown): string;
|
|
100
|
+
/** Decrypt and deserialize a payload produced by {@link Encrypter.encrypt}. The `decrypt()` equivalent. */
|
|
101
|
+
decrypt(payload: string): unknown;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Authentication contracts — the Laravel `Illuminate\Contracts\Auth` interfaces.
|
|
106
|
+
* {@link Authenticatable} is a user that can be authenticated; {@link UserProvider} retrieves and
|
|
107
|
+
* validates users from storage; {@link Guard} reads who the current user is; {@link StatefulGuard}
|
|
108
|
+
* also logs them in and out across requests; {@link Rememberable} adds "remember me" persistence.
|
|
109
|
+
*/
|
|
110
|
+
/** A user that can be authenticated — the `Illuminate\Contracts\Auth\Authenticatable` equivalent. */
|
|
111
|
+
interface Authenticatable {
|
|
112
|
+
/** The unique identifier (primary key) for the user. */
|
|
113
|
+
getAuthIdentifier(): string | number;
|
|
114
|
+
/** The name of the identifier field (e.g. `id`). */
|
|
115
|
+
getAuthIdentifierName(): string;
|
|
116
|
+
/** The hashed password used to validate credentials. */
|
|
117
|
+
getAuthPassword(): string;
|
|
118
|
+
}
|
|
119
|
+
/** Login credentials — typically `{ email, password }`. The Laravel credentials array equivalent. */
|
|
120
|
+
type Credentials = Record<string, unknown>;
|
|
121
|
+
/**
|
|
122
|
+
* A user that supports "remember me" persistence — the Laravel remember-token methods on
|
|
123
|
+
* `Authenticatable`. Kept separate so a user can opt into it independently.
|
|
124
|
+
*/
|
|
125
|
+
interface Rememberable {
|
|
126
|
+
/** The persisted remember-me token, or `null` if none. */
|
|
127
|
+
getRememberToken(): string | null;
|
|
128
|
+
/** Persist (in memory) a new remember-me token. */
|
|
129
|
+
setRememberToken(token: string): void;
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Retrieves and validates users from storage — the `Illuminate\Contracts\Auth\UserProvider`
|
|
133
|
+
* equivalent. The seam between a guard and however users are persisted.
|
|
134
|
+
*/
|
|
135
|
+
interface UserProvider {
|
|
136
|
+
/** Find a user by primary key, or `null`. */
|
|
137
|
+
retrieveById(identifier: string | number): Promise<Authenticatable | null>;
|
|
138
|
+
/** Find a user by primary key whose remember-me token matches, or `null` (constant-time). */
|
|
139
|
+
retrieveByToken(identifier: string | number, token: string): Promise<Authenticatable | null>;
|
|
140
|
+
/** Persist a new remember-me token for `user`. */
|
|
141
|
+
updateRememberToken(user: Authenticatable, token: string): Promise<void>;
|
|
142
|
+
/** Find a user matching the non-password credentials, or `null`. */
|
|
143
|
+
retrieveByCredentials(credentials: Credentials): Promise<Authenticatable | null>;
|
|
144
|
+
/** Whether `credentials` validate against `user` (constant-time password check). */
|
|
145
|
+
validateCredentials(user: Authenticatable, credentials: Credentials): Promise<boolean>;
|
|
146
|
+
}
|
|
147
|
+
/** A read-only authentication guard — the `Illuminate\Contracts\Auth\Guard` equivalent. */
|
|
148
|
+
interface Guard {
|
|
149
|
+
/** Whether a user is authenticated. */
|
|
150
|
+
check(): Promise<boolean>;
|
|
151
|
+
/** Whether no user is authenticated. */
|
|
152
|
+
guest(): Promise<boolean>;
|
|
153
|
+
/** The authenticated user, or `null`. */
|
|
154
|
+
user(): Promise<Authenticatable | null>;
|
|
155
|
+
/** The authenticated user's identifier, or `null`. */
|
|
156
|
+
id(): Promise<string | number | null>;
|
|
157
|
+
/** Whether the credentials are valid, without logging anyone in. */
|
|
158
|
+
validate(credentials: Credentials): Promise<boolean>;
|
|
159
|
+
/** Set the current user explicitly (e.g. after registration). */
|
|
160
|
+
setUser(user: Authenticatable): void;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* A guard that can also log users in and out across requests — the
|
|
164
|
+
* `Illuminate\Contracts\Auth\StatefulGuard` equivalent.
|
|
165
|
+
*/
|
|
166
|
+
interface StatefulGuard extends Guard {
|
|
167
|
+
/** Validate credentials and, on success, log the user in. */
|
|
168
|
+
attempt(credentials: Credentials): Promise<boolean>;
|
|
169
|
+
/** Validate credentials and set the user for this request only (no persistence). */
|
|
170
|
+
once(credentials: Credentials): Promise<boolean>;
|
|
171
|
+
/** Log a user in (persist their id). */
|
|
172
|
+
login(user: Authenticatable): void;
|
|
173
|
+
/** Log in by identifier, returning the user (or `null` if unknown). */
|
|
174
|
+
loginUsingId(id: string | number): Promise<Authenticatable | null>;
|
|
175
|
+
/** Log the current user out. */
|
|
176
|
+
logout(): void;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Cache contracts — the Laravel `Illuminate\Contracts\Cache` interfaces. {@link CacheStore} is the
|
|
181
|
+
* lowest layer (the swappable backend: array, file, Redis); {@link CacheRepository} is the
|
|
182
|
+
* 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`.
|
|
185
|
+
*/
|
|
186
|
+
/**
|
|
187
|
+
* The cache store — the `Illuminate\Contracts\Cache\Store` equivalent. The minimal persistence
|
|
188
|
+
* surface every backend implements; the {@link CacheRepository} is layered over it.
|
|
189
|
+
*/
|
|
190
|
+
interface CacheStore {
|
|
191
|
+
/** Fetch a value by key, or `null` when missing/expired. The `get` equivalent. */
|
|
192
|
+
get<T = unknown>(key: string): Promise<T | null>;
|
|
193
|
+
/** Store a value for `ttlSeconds` (or forever when omitted). The `put` equivalent. */
|
|
194
|
+
put<T>(key: string, value: T, ttlSeconds?: number): Promise<boolean>;
|
|
195
|
+
/** Store a value that never expires. The `forever` equivalent. */
|
|
196
|
+
forever<T>(key: string, value: T): Promise<boolean>;
|
|
197
|
+
/** Remove a key, returning whether it existed. The `forget` equivalent. */
|
|
198
|
+
forget(key: string): Promise<boolean>;
|
|
199
|
+
/** Remove every key. The `flush` equivalent. */
|
|
200
|
+
flush(): Promise<boolean>;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
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,
|
|
205
|
+
* the read-and-delete `pull`, and existence/atomic-counter helpers.
|
|
206
|
+
*/
|
|
207
|
+
interface CacheRepository extends CacheStore {
|
|
208
|
+
/** Whether a live value exists for the key. The `has` equivalent. */
|
|
209
|
+
has(key: string): Promise<boolean>;
|
|
210
|
+
/** Store only if absent, returning whether it was written. The `add` equivalent. */
|
|
211
|
+
add<T>(key: string, value: T, ttlSeconds?: number): Promise<boolean>;
|
|
212
|
+
/** Atomically add `by` to a numeric key, returning the new value. The `increment` equivalent. */
|
|
213
|
+
increment(key: string, by?: number): Promise<number>;
|
|
214
|
+
/** Atomically subtract `by` from a numeric key, returning the new value. The `decrement` equivalent. */
|
|
215
|
+
decrement(key: string, by?: number): Promise<number>;
|
|
216
|
+
/** Fetch a value and remove it in one shot, or `null` when missing. The `pull` equivalent. */
|
|
217
|
+
pull<T = unknown>(key: string): Promise<T | null>;
|
|
218
|
+
/** Return the cached value, or compute it via `callback`, store it for `ttlSeconds`, and return it. The `remember` equivalent. */
|
|
219
|
+
remember<T>(key: string, ttlSeconds: number, callback: () => T | Promise<T>): Promise<T>;
|
|
220
|
+
/** Like {@link CacheRepository.remember} but stores the value forever. The `rememberForever` equivalent. */
|
|
221
|
+
rememberForever<T>(key: string, callback: () => T | Promise<T>): Promise<T>;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
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
|
|
227
|
+
* the unit of deferred work whose `handle()` a driver runs; {@link JobMiddleware} wraps that call
|
|
228
|
+
* with cross-cutting concerns. {@link Queueable} is the alias used where a queueable job is expected.
|
|
229
|
+
*/
|
|
230
|
+
/**
|
|
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.
|
|
233
|
+
*/
|
|
234
|
+
interface ShouldQueue {
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* The unit of deferred work — the `ShouldQueue` + `Illuminate\Bus\Queueable` equivalent. A driver
|
|
238
|
+
* `await`s {@link QueueJob.handle}; an optional {@link QueueJob.tries} bounds attempts before the
|
|
239
|
+
* job is treated as failed, and {@link QueueJob.middleware} wraps the call to `handle`.
|
|
240
|
+
*/
|
|
241
|
+
interface QueueJob {
|
|
242
|
+
/** Run the job's work. The `handle()` equivalent — may be sync or async; drivers always await it. */
|
|
243
|
+
handle(): Promise<void> | void;
|
|
244
|
+
/** Maximum number of attempts before the job is treated as failed — the `$tries` equivalent. */
|
|
245
|
+
tries?: number;
|
|
246
|
+
/** Return the middleware pipeline that wraps {@link QueueJob.handle}. The `middleware()` equivalent. */
|
|
247
|
+
middleware?(): JobMiddleware[];
|
|
248
|
+
}
|
|
249
|
+
/** Alias of {@link QueueJob} — used where a queueable job is expected (the `Queueable` concept). */
|
|
250
|
+
type Queueable = QueueJob;
|
|
251
|
+
/**
|
|
252
|
+
* One link in a job's middleware pipeline — the Laravel job-middleware (`handle($job, $next)`)
|
|
253
|
+
* equivalent, expressed as a function. Awaiting `next()` runs the rest of the pipeline (and
|
|
254
|
+
* ultimately `handle`); skipping it short-circuits the job.
|
|
255
|
+
*/
|
|
256
|
+
type JobMiddleware = (job: QueueJob, next: () => Promise<void>) => Promise<void> | void;
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* Mail contracts — the Laravel `Illuminate\Contracts\Mail` interfaces. A {@link MailableContract}
|
|
260
|
+
* is a self-describing email that configures itself via `build()` and can `render()` itself; a
|
|
261
|
+
* {@link Mailer} dispatches one through whatever transport backs it. Kept transport-agnostic so the
|
|
262
|
+
* sender never cares which delivery mechanism is wired up.
|
|
263
|
+
*/
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* A self-describing email — the `Illuminate\Contracts\Mail\Mailable` equivalent. {@link
|
|
267
|
+
* MailableContract.build} configures the message (recipients, subject, body) before it is sent;
|
|
268
|
+
* {@link Renderable.render} produces its rendered form for previewing or inlining.
|
|
269
|
+
*/
|
|
270
|
+
interface MailableContract extends Renderable {
|
|
271
|
+
/** Configure the message before sending. The `build()` equivalent (invoked once by the mailer). */
|
|
272
|
+
build(): void;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* The mailer — the `Illuminate\Contracts\Mail\Mailer` equivalent and the `Mail` facade surface.
|
|
276
|
+
* {@link Mailer.send} runs a mailable's lifecycle and dispatches it through the bound transport.
|
|
277
|
+
*/
|
|
278
|
+
interface Mailer {
|
|
279
|
+
/** Run a mailable's lifecycle and dispatch it. The `send()` equivalent. */
|
|
280
|
+
send(mailable: MailableContract): Promise<void>;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Filesystem contract — the Laravel `Illuminate\Contracts\Filesystem\Filesystem` equivalent. A
|
|
285
|
+
* {@link Disk} is a single named storage location (local directory, in-memory tree, cloud bucket)
|
|
286
|
+
* exposed as a uniform async API, so the layer above never cares which driver backs it. This is the
|
|
287
|
+
* common read/write/exists/delete/list subset; concrete disks may offer more. Paths are POSIX-style
|
|
288
|
+
* and relative to the disk root.
|
|
289
|
+
*/
|
|
290
|
+
/**
|
|
291
|
+
* The core filesystem surface — the common subset of `Illuminate\Contracts\Filesystem\Filesystem`.
|
|
292
|
+
* Every method is async so a driver may be backed by network or disk I/O.
|
|
293
|
+
*/
|
|
294
|
+
interface Disk {
|
|
295
|
+
/** Read a file's contents as a UTF-8 string. Rejects when the file is missing. The `get` equivalent. */
|
|
296
|
+
get(path: string): Promise<string>;
|
|
297
|
+
/** Write `contents` to a file, creating parent directories as needed. The `put` equivalent. */
|
|
298
|
+
put(path: string, contents: string): Promise<boolean>;
|
|
299
|
+
/** Whether a file or directory exists at `path`. The `exists` equivalent. */
|
|
300
|
+
exists(path: string): Promise<boolean>;
|
|
301
|
+
/** Remove a file, returning `true` when it existed. The `delete` equivalent. */
|
|
302
|
+
delete(path: string): Promise<boolean>;
|
|
303
|
+
/** Relative paths of the files directly within `dir` (non-recursive). The `files` equivalent. */
|
|
304
|
+
files(dir?: string): Promise<string[]>;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Container contract — the Laravel `Illuminate\Contracts\Container\Container` equivalent. A
|
|
309
|
+
* {@link Container} resolves dependencies by identifier (a string/symbol token or a class
|
|
310
|
+
* constructor): {@link Container.bind} registers a factory, {@link Container.singleton} registers a
|
|
311
|
+
* shared one, {@link Container.make} resolves it, and {@link Container.bound} reports registration.
|
|
312
|
+
* JS has no reflection-based autowiring, so dependencies are wired via factory functions.
|
|
313
|
+
*/
|
|
314
|
+
/**
|
|
315
|
+
* A class constructor — the seam a container can `new` directly. The constructor signature is
|
|
316
|
+
* intentionally open so any class is assignable.
|
|
317
|
+
*/
|
|
318
|
+
type Newable<T = unknown> = new (...args: any[]) => T;
|
|
319
|
+
/** A thing that can identify a binding: a string/symbol token or a class constructor. */
|
|
320
|
+
type Identifier<T = unknown> = string | symbol | Newable<T>;
|
|
321
|
+
/**
|
|
322
|
+
* The service container — the `Illuminate\Contracts\Container\Container` equivalent. The minimal
|
|
323
|
+
* bind/resolve surface application code holds; concrete containers add aliasing, tagging, and
|
|
324
|
+
* contextual binding on top.
|
|
325
|
+
*/
|
|
326
|
+
interface Container {
|
|
327
|
+
/** Register a binding from an identifier to a factory or constructable class. The `bind` equivalent. */
|
|
328
|
+
bind<T>(token: Identifier<T>, concrete?: Newable<T>): void;
|
|
329
|
+
/** Register a shared (singleton) binding — resolved once, then cached. The `singleton` equivalent. */
|
|
330
|
+
singleton<T>(token: Identifier<T>, concrete?: Newable<T>): void;
|
|
331
|
+
/** Resolve an identifier to a concrete value. The `make` equivalent. */
|
|
332
|
+
make<T>(token: Identifier<T>): T;
|
|
333
|
+
/** Whether anything is registered for this identifier. The `bound` equivalent. */
|
|
334
|
+
bound(token: Identifier): boolean;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Cast contracts — the Laravel `Illuminate\Contracts\Database\Eloquent\CastsAttributes` equivalent.
|
|
339
|
+
* A {@link Cast} transforms an attribute between its database-shaped value and its in-memory
|
|
340
|
+
* representation on read/write; {@link CastEncrypter} is the minimal encrypt/decrypt surface an
|
|
341
|
+
* encrypting cast needs. The owning model is passed as `unknown` to keep this package decoupled.
|
|
342
|
+
*/
|
|
343
|
+
/**
|
|
344
|
+
* A custom attribute cast — the `CastsAttributes` equivalent. {@link Cast.get} runs on read,
|
|
345
|
+
* {@link Cast.set} on write. The `model` is the owning record, typed `unknown` so this contract
|
|
346
|
+
* stays free of any ORM dependency.
|
|
347
|
+
*/
|
|
348
|
+
interface Cast {
|
|
349
|
+
/** Transform the DB-shaped value into its in-memory representation. The `get` equivalent. */
|
|
350
|
+
get(value: unknown, model: unknown): unknown;
|
|
351
|
+
/** Transform an in-memory value back into its DB-shaped representation. The `set` equivalent. */
|
|
352
|
+
set(value: unknown, model: unknown): unknown;
|
|
353
|
+
}
|
|
354
|
+
/**
|
|
355
|
+
* The minimal encrypt/decrypt surface an encrypting cast needs — a structural subset of the
|
|
356
|
+
* encryption `Encrypter`. Kept here so a cast can depend on it without importing the encrypter type.
|
|
357
|
+
*/
|
|
358
|
+
interface CastEncrypter {
|
|
359
|
+
/** Serialize and encrypt a value into an opaque payload string. */
|
|
360
|
+
encrypt(value: unknown): string;
|
|
361
|
+
/** Decrypt and deserialize a payload produced by {@link CastEncrypter.encrypt}. */
|
|
362
|
+
decrypt(payload: string): unknown;
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
/**
|
|
366
|
+
* `@plinthjs/contracts` — the interface-only foundation, the `Illuminate\Contracts` equivalent. This
|
|
367
|
+
* 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
|
|
369
|
+
* {@link VERSION}.
|
|
370
|
+
*/
|
|
371
|
+
|
|
372
|
+
/** The Mason version this build of `contracts` ships with. */
|
|
373
|
+
declare const VERSION = "0.1.0";
|
|
374
|
+
|
|
375
|
+
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
ADDED
|
@@ -0,0 +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"]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,58 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@plinthjs/contracts",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Mason contracts: the interface-only foundation (the Illuminate\\Contracts equivalent).",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"mason",
|
|
7
|
+
"laravel",
|
|
8
|
+
"framework",
|
|
9
|
+
"typescript",
|
|
10
|
+
"contracts"
|
|
11
|
+
],
|
|
12
|
+
"homepage": "https://github.com/anilkumarthakur60/js-framework/tree/main/packages/contracts#readme",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/anilkumarthakur60/js-framework/issues"
|
|
15
|
+
},
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "git+https://github.com/anilkumarthakur60/js-framework.git",
|
|
19
|
+
"directory": "packages/contracts"
|
|
20
|
+
},
|
|
21
|
+
"license": "MIT",
|
|
22
|
+
"author": "Er. Anil Kumar Thakur",
|
|
23
|
+
"type": "module",
|
|
24
|
+
"sideEffects": false,
|
|
25
|
+
"files": [
|
|
26
|
+
"dist"
|
|
27
|
+
],
|
|
28
|
+
"exports": {
|
|
29
|
+
".": {
|
|
30
|
+
"types": "./dist/index.d.ts",
|
|
31
|
+
"import": "./dist/index.js",
|
|
32
|
+
"require": "./dist/index.cjs"
|
|
33
|
+
},
|
|
34
|
+
"./package.json": "./package.json"
|
|
35
|
+
},
|
|
36
|
+
"main": "./dist/index.cjs",
|
|
37
|
+
"module": "./dist/index.js",
|
|
38
|
+
"types": "./dist/index.d.ts",
|
|
39
|
+
"engines": {
|
|
40
|
+
"node": ">=20"
|
|
41
|
+
},
|
|
42
|
+
"publishConfig": {
|
|
43
|
+
"access": "public"
|
|
44
|
+
},
|
|
45
|
+
"devDependencies": {
|
|
46
|
+
"@types/node": "^22.10.0",
|
|
47
|
+
"tsup": "^8.3.5",
|
|
48
|
+
"typescript": "^5.7.2",
|
|
49
|
+
"vitest": "^3.0.0"
|
|
50
|
+
},
|
|
51
|
+
"scripts": {
|
|
52
|
+
"build": "tsup",
|
|
53
|
+
"dev": "tsup --watch",
|
|
54
|
+
"test": "vitest run",
|
|
55
|
+
"typecheck": "tsc --noEmit",
|
|
56
|
+
"clean": "rm -rf dist .turbo *.tsbuildinfo"
|
|
57
|
+
}
|
|
6
58
|
}
|