@molecule/api-resource-follow 1.0.0 → 1.0.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/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.
@@ -1 +1 @@
1
- {"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/handlers/list.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAI/E;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BrF"}
1
+ {"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/handlers/list.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAO/E;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BrF"}
@@ -6,6 +6,8 @@
6
6
  import { t } from '@molecule/api-i18n';
7
7
  import { logger } from '@molecule/api-logger';
8
8
  import { getFollowers } from '../service.js';
9
+ /** Upper bound for the list page size — an uncapped `limit` is a table-dump primitive (e.g. `?limit=999999999`). */
10
+ const MAX_LIST_LIMIT = 500;
9
11
  /**
10
12
  * Lists paginated followers of a target.
11
13
  *
@@ -23,7 +25,7 @@ export async function list(req, res) {
23
25
  });
24
26
  return;
25
27
  }
26
- const limit = parseInt(req.query.limit, 10) || 20;
28
+ const limit = Math.min(MAX_LIST_LIMIT, Math.max(1, parseInt(req.query.limit, 10) || 20));
27
29
  const offset = parseInt(req.query.offset, 10) || 0;
28
30
  try {
29
31
  const result = await getFollowers(targetType, targetId, { limit, offset });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-resource-follow",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
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",
@@ -29,13 +30,13 @@
29
30
  "devDependencies": {
30
31
  "@types/node": "26.1.2",
31
32
  "typescript": "6.0.3",
32
- "vitest": "4.1.10"
33
+ "vitest": "4.1.11"
33
34
  },
34
35
  "peerDependencies": {
35
- "@molecule/api-database": "^1.0.0",
36
- "@molecule/api-i18n": "^1.0.0",
37
- "@molecule/api-logger": "^1.0.0",
38
- "@molecule/api-resource": "^1.0.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": {