@molecule/api-resource-follow 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +368 -0
- package/package.json +7 -6
package/README.md
ADDED
|
@@ -0,0 +1,368 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-08-04T01:49:12.748Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
9
|
+
# @molecule/api-resource-follow
|
|
10
|
+
|
|
11
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
12
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
13
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
14
|
+
|
|
15
|
+
Follow/unfollow resource for molecule.dev.
|
|
16
|
+
|
|
17
|
+
Polymorphic follow system for users or any resource type. Supports
|
|
18
|
+
followers list, following list, and follow status checks.
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import { routes, requestHandlerMap } from '@molecule/api-resource-follow'
|
|
24
|
+
|
|
25
|
+
// Wire routes into your Express app via mlcl inject
|
|
26
|
+
// POST /follow/:targetType/:targetId
|
|
27
|
+
// DELETE /follow/:targetType/:targetId
|
|
28
|
+
// GET /:targetType/:targetId/followers
|
|
29
|
+
// GET /following
|
|
30
|
+
// GET /follow/check/:targetType/:targetId
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Type
|
|
34
|
+
|
|
35
|
+
`resource`
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install @molecule/api-resource-follow @molecule/api-database @molecule/api-i18n @molecule/api-logger @molecule/api-resource
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## API
|
|
44
|
+
|
|
45
|
+
### Interfaces
|
|
46
|
+
|
|
47
|
+
#### `Follow`
|
|
48
|
+
|
|
49
|
+
A follow relationship between a user and a target resource.
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
interface Follow {
|
|
53
|
+
/** Unique follow identifier. */
|
|
54
|
+
id: string
|
|
55
|
+
/** The ID of the user who is following. */
|
|
56
|
+
followerId: string
|
|
57
|
+
/** The type of target being followed (e.g. 'user', 'project'). */
|
|
58
|
+
targetType: string
|
|
59
|
+
/** The ID of the target being followed. */
|
|
60
|
+
targetId: string
|
|
61
|
+
/** When the follow was created (ISO 8601). */
|
|
62
|
+
createdAt: string
|
|
63
|
+
/** When the follow was last updated (ISO 8601). */
|
|
64
|
+
updatedAt: string
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
#### `PaginatedResult`
|
|
69
|
+
|
|
70
|
+
A paginated result set.
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
interface PaginatedResult<T> {
|
|
74
|
+
/** The result items for the current page. */
|
|
75
|
+
data: T[]
|
|
76
|
+
/** Total number of matching items across all pages. */
|
|
77
|
+
total: number
|
|
78
|
+
/** Maximum number of results per page. */
|
|
79
|
+
limit: number
|
|
80
|
+
/** Number of results skipped. */
|
|
81
|
+
offset: number
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
#### `PaginationOptions`
|
|
86
|
+
|
|
87
|
+
Options for paginated queries.
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
interface PaginationOptions {
|
|
91
|
+
/** Maximum number of results to return. */
|
|
92
|
+
limit?: number
|
|
93
|
+
/** Number of results to skip. */
|
|
94
|
+
offset?: number
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Functions
|
|
99
|
+
|
|
100
|
+
#### `checkFollowing(req, res)`
|
|
101
|
+
|
|
102
|
+
Checks if the current user is following a target.
|
|
103
|
+
|
|
104
|
+
```typescript
|
|
105
|
+
function checkFollowing(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
- `req` — The request with `targetType` and `targetId` params.
|
|
109
|
+
- `res` — The response object.
|
|
110
|
+
|
|
111
|
+
#### `create(req, res)`
|
|
112
|
+
|
|
113
|
+
Creates a follow relationship. Idempotent.
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
function create(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
- `req` — The request with `targetType` and `targetId` params.
|
|
120
|
+
- `res` — The response object.
|
|
121
|
+
|
|
122
|
+
#### `del(req, res)`
|
|
123
|
+
|
|
124
|
+
Removes a follow relationship.
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
function del(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
- `req` — The request with `targetType` and `targetId` params.
|
|
131
|
+
- `res` — The response object.
|
|
132
|
+
|
|
133
|
+
#### `follow(followerId, targetType, targetId)`
|
|
134
|
+
|
|
135
|
+
Creates a follow relationship. Idempotent — returns existing follow if already following.
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
function follow(followerId: string, targetType: string, targetId: string): Promise<Follow>
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- `followerId` — The ID of the follower.
|
|
142
|
+
- `targetType` — The type of target being followed.
|
|
143
|
+
- `targetId` — The ID of the target being followed.
|
|
144
|
+
|
|
145
|
+
**Returns:** The created or existing follow.
|
|
146
|
+
|
|
147
|
+
#### `following(req, res)`
|
|
148
|
+
|
|
149
|
+
Lists targets the current user is following.
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
function following(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
- `req` — The request with pagination query params.
|
|
156
|
+
- `res` — The response object.
|
|
157
|
+
|
|
158
|
+
#### `getFollowerCount(targetType, targetId)`
|
|
159
|
+
|
|
160
|
+
Gets the follower count for a target.
|
|
161
|
+
|
|
162
|
+
```typescript
|
|
163
|
+
function getFollowerCount(targetType: string, targetId: string): Promise<number>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
- `targetType` — The type of target.
|
|
167
|
+
- `targetId` — The ID of the target.
|
|
168
|
+
|
|
169
|
+
**Returns:** The number of followers.
|
|
170
|
+
|
|
171
|
+
#### `getFollowers(targetType, targetId, options)`
|
|
172
|
+
|
|
173
|
+
Gets paginated followers of a target.
|
|
174
|
+
|
|
175
|
+
```typescript
|
|
176
|
+
function getFollowers(
|
|
177
|
+
targetType: string,
|
|
178
|
+
targetId: string,
|
|
179
|
+
options?: PaginationOptions,
|
|
180
|
+
): Promise<PaginatedResult<Follow>>
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
- `targetType` — The type of target.
|
|
184
|
+
- `targetId` — The ID of the target.
|
|
185
|
+
- `options` — Pagination options.
|
|
186
|
+
|
|
187
|
+
**Returns:** Paginated followers.
|
|
188
|
+
|
|
189
|
+
#### `getFollowing(userId, options)`
|
|
190
|
+
|
|
191
|
+
Gets paginated targets a user is following.
|
|
192
|
+
|
|
193
|
+
```typescript
|
|
194
|
+
function getFollowing(userId: string, options?: PaginationOptions): Promise<PaginatedResult<Follow>>
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- `userId` — The follower's user ID.
|
|
198
|
+
- `options` — Pagination options.
|
|
199
|
+
|
|
200
|
+
**Returns:** Paginated follows.
|
|
201
|
+
|
|
202
|
+
#### `getFollowingCount(userId)`
|
|
203
|
+
|
|
204
|
+
Gets the following count for a user.
|
|
205
|
+
|
|
206
|
+
```typescript
|
|
207
|
+
function getFollowingCount(userId: string): Promise<number>
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
- `userId` — The user ID.
|
|
211
|
+
|
|
212
|
+
**Returns:** The number of targets the user is following.
|
|
213
|
+
|
|
214
|
+
#### `isFollowing(followerId, targetType, targetId)`
|
|
215
|
+
|
|
216
|
+
Checks if a user is following a target.
|
|
217
|
+
|
|
218
|
+
```typescript
|
|
219
|
+
function isFollowing(followerId: string, targetType: string, targetId: string): Promise<boolean>
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
- `followerId` — The follower's user ID.
|
|
223
|
+
- `targetType` — The type of target.
|
|
224
|
+
- `targetId` — The ID of the target.
|
|
225
|
+
|
|
226
|
+
**Returns:** `true` if following.
|
|
227
|
+
|
|
228
|
+
#### `list(req, res)`
|
|
229
|
+
|
|
230
|
+
Lists paginated followers of a target.
|
|
231
|
+
|
|
232
|
+
```typescript
|
|
233
|
+
function list(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
- `req` — The request with `targetType` and `targetId` params.
|
|
237
|
+
- `res` — The response object.
|
|
238
|
+
|
|
239
|
+
#### `unfollow(followerId, targetType, targetId)`
|
|
240
|
+
|
|
241
|
+
Removes a follow relationship.
|
|
242
|
+
|
|
243
|
+
```typescript
|
|
244
|
+
function unfollow(followerId: string, targetType: string, targetId: string): Promise<void>
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
- `followerId` — The ID of the follower.
|
|
248
|
+
- `targetType` — The type of target.
|
|
249
|
+
- `targetId` — The ID of the target.
|
|
250
|
+
|
|
251
|
+
### Constants
|
|
252
|
+
|
|
253
|
+
#### `requestHandlerMap`
|
|
254
|
+
|
|
255
|
+
Handler map for follow routes.
|
|
256
|
+
|
|
257
|
+
```typescript
|
|
258
|
+
const requestHandlerMap: {
|
|
259
|
+
readonly create: typeof create
|
|
260
|
+
readonly del: typeof del
|
|
261
|
+
readonly list: typeof list
|
|
262
|
+
readonly following: typeof following
|
|
263
|
+
readonly checkFollowing: typeof checkFollowing
|
|
264
|
+
}
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
#### `routes`
|
|
268
|
+
|
|
269
|
+
Routes for follow/unfollow, followers, following, and status check.
|
|
270
|
+
|
|
271
|
+
```typescript
|
|
272
|
+
const routes: readonly [
|
|
273
|
+
{
|
|
274
|
+
readonly method: 'post'
|
|
275
|
+
readonly path: '/follow/:targetType/:targetId'
|
|
276
|
+
readonly handler: 'create'
|
|
277
|
+
readonly middlewares: readonly ['authenticate']
|
|
278
|
+
},
|
|
279
|
+
{
|
|
280
|
+
readonly method: 'delete'
|
|
281
|
+
readonly path: '/follow/:targetType/:targetId'
|
|
282
|
+
readonly handler: 'del'
|
|
283
|
+
readonly middlewares: readonly ['authenticate']
|
|
284
|
+
},
|
|
285
|
+
{
|
|
286
|
+
readonly method: 'get'
|
|
287
|
+
readonly path: '/:targetType/:targetId/followers'
|
|
288
|
+
readonly handler: 'list'
|
|
289
|
+
},
|
|
290
|
+
{
|
|
291
|
+
readonly method: 'get'
|
|
292
|
+
readonly path: '/following'
|
|
293
|
+
readonly handler: 'following'
|
|
294
|
+
readonly middlewares: readonly ['authenticate']
|
|
295
|
+
},
|
|
296
|
+
{
|
|
297
|
+
readonly method: 'get'
|
|
298
|
+
readonly path: '/follow/check/:targetType/:targetId'
|
|
299
|
+
readonly handler: 'checkFollowing'
|
|
300
|
+
readonly middlewares: readonly ['authenticate']
|
|
301
|
+
},
|
|
302
|
+
]
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
## Injection Notes
|
|
306
|
+
|
|
307
|
+
### Requirements
|
|
308
|
+
|
|
309
|
+
Peer dependencies:
|
|
310
|
+
|
|
311
|
+
- `@molecule/api-database` ^1.0.1
|
|
312
|
+
- `@molecule/api-i18n` ^1.0.1
|
|
313
|
+
- `@molecule/api-logger` ^1.0.1
|
|
314
|
+
- `@molecule/api-resource` ^1.0.1
|
|
315
|
+
|
|
316
|
+
### Runtime Dependencies
|
|
317
|
+
|
|
318
|
+
- `@molecule/api-database`
|
|
319
|
+
- `@molecule/api-i18n`
|
|
320
|
+
- `@molecule/api-logger`
|
|
321
|
+
- `@molecule/api-resource`
|
|
322
|
+
|
|
323
|
+
- **List endpoints return a PAGINATED envelope** `{ data, total, limit, offset }`, not a
|
|
324
|
+
bare array — read the rows off `result.data` (server). On the client, `unwrapList(res)`
|
|
325
|
+
from `@molecule/app-http` normalizes this envelope (pass it the whole HttpResponse), so
|
|
326
|
+
the rows come back; reading the response as a bare array — or `res.data` alone (which is
|
|
327
|
+
the envelope) — yields an EMPTY list.
|
|
328
|
+
Table: `src/__setup__/follows.sql` creates the single `follows` table. An
|
|
329
|
+
mlcl-scaffolded API replays `__setup__/*.sql` automatically on migrate;
|
|
330
|
+
anywhere else run it once — nothing at runtime creates it.
|
|
331
|
+
|
|
332
|
+
The follower is ALWAYS the authenticated user: handlers read
|
|
333
|
+
`res.locals.session` (populated by your global auth middleware) and 401
|
|
334
|
+
without it — never accept a follower userId from the body or params.
|
|
335
|
+
`GET /:targetType/:targetId/followers` is deliberately PUBLIC; gate it
|
|
336
|
+
yourself if follower lists are private in your app.
|
|
337
|
+
|
|
338
|
+
`targetType` is a free-form string (`user`, `post`, …) — the package does
|
|
339
|
+
not validate it against your schema, so constrain accepted values in your
|
|
340
|
+
app if arbitrary types would be a problem.
|
|
341
|
+
|
|
342
|
+
## E2E Tests
|
|
343
|
+
|
|
344
|
+
Integration checklist — drive the real UI (live preview, no mocks), adapt
|
|
345
|
+
each item to this app's actual screens/flows, and check every box off one
|
|
346
|
+
by one. A box you can't check is an integration bug to fix — not a skip:
|
|
347
|
+
|
|
348
|
+
- [ ] User A follows user B (`POST /follow/user/:B`): B's follower count and
|
|
349
|
+
A's following count each increment by exactly one, B appears in A's
|
|
350
|
+
following list (`GET /following`) and A appears in B's followers list
|
|
351
|
+
(`GET /user/:B/followers`). Reload — the edge and both counts persist (it's
|
|
352
|
+
a real `follows` row, not local UI state).
|
|
353
|
+
- [ ] Following is IDEMPOTENT: A following B a second time (double-tap Follow
|
|
354
|
+
or replay the POST) creates NO duplicate edge and does NOT double-count —
|
|
355
|
+
exactly one `follows` row exists for (A → B) and both counts are unchanged.
|
|
356
|
+
- [ ] Unfollow (`DELETE /follow/user/:B`) removes the edge: A's following
|
|
357
|
+
count and B's follower count each decrement back, B leaves A's following
|
|
358
|
+
list, A leaves B's followers, and `GET /follow/check/user/:B` now returns
|
|
359
|
+
`{ following: false }`.
|
|
360
|
+
- [ ] You cannot follow yourself: the UI never offers Follow on your own
|
|
361
|
+
profile, and following your own id never inflates your own counts. This
|
|
362
|
+
package's `follow()` does not reject `followerId === targetId`, so the app
|
|
363
|
+
must guard it — verify the guard exists, don't assume it.
|
|
364
|
+
- [ ] AUTHORIZATION — the follower is ALWAYS the session user: handlers read
|
|
365
|
+
`res.locals.session` and 401 without it, so no UI or endpoint lets you
|
|
366
|
+
follow/unfollow on behalf of another user by passing their id, and
|
|
367
|
+
follow/unfollow act only on your own edges. Signed in as A you can never
|
|
368
|
+
make B follow or unfollow anyone.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/api-resource-follow",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Follow/unfollow users or any resource with polymorphic targeting",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -17,7 +17,8 @@
|
|
|
17
17
|
}
|
|
18
18
|
},
|
|
19
19
|
"files": [
|
|
20
|
-
"dist"
|
|
20
|
+
"dist",
|
|
21
|
+
"README.md"
|
|
21
22
|
],
|
|
22
23
|
"keywords": [
|
|
23
24
|
"molecule",
|
|
@@ -32,10 +33,10 @@
|
|
|
32
33
|
"vitest": "4.1.10"
|
|
33
34
|
},
|
|
34
35
|
"peerDependencies": {
|
|
35
|
-
"@molecule/api-database": "^1.0.
|
|
36
|
-
"@molecule/api-i18n": "^1.0.
|
|
37
|
-
"@molecule/api-logger": "^1.0.
|
|
38
|
-
"@molecule/api-resource": "^1.0.
|
|
36
|
+
"@molecule/api-database": "^1.0.1",
|
|
37
|
+
"@molecule/api-i18n": "^1.0.1",
|
|
38
|
+
"@molecule/api-logger": "^1.0.1",
|
|
39
|
+
"@molecule/api-resource": "^1.0.1"
|
|
39
40
|
},
|
|
40
41
|
"peerDependenciesMeta": {
|
|
41
42
|
"@molecule/api-database": {
|