@molecule/api-resource-follow 1.1.1 → 1.1.3

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 CHANGED
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-11-12T13:52:29.784Z
6
+ Generated: 2026-11-19T03:20:25.163Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-resource-follow
@@ -17,6 +17,35 @@ Use `getFollowedIds(viewerId, targetType, ids)` once per displayed collection, t
17
17
  deduplicates ids, and does no I/O for an empty page or an absent viewer. It works for
18
18
  any target type, including documents, topics and users. Use `isFollowing` for one target.
19
19
 
20
+ **Custom routes use the same services.** A profile route, username parameter or
21
+ different response envelope does not require the package's HTTP routes. Resolve
22
+ the username in the app, then call `follow(viewerId, 'user', profile.id)`,
23
+ `unfollow(viewerId, 'user', profile.id)` or
24
+ `isFollowing(viewerId, 'user', profile.id)` and project the profile locally.
25
+ `isFollowing` accepts `string | null | undefined`; an absent viewer returns
26
+ `false` without a database read. Mutations still require an authenticated id.
27
+
28
+ These services use the package's `follows` table, with `followerId`, `targetType`
29
+ and `targetId`. For users, `targetId` is the canonical user id, never the username.
30
+ A genuinely different relationship schema stays local; these calls do not read a
31
+ custom `followingId` column or a separate table.
32
+
33
+ ```typescript
34
+ import { getFollowedIds } from '@molecule/api-resource-follow'
35
+
36
+ export async function projectWatchedNotes(
37
+ notes: readonly { id: string; title: string }[],
38
+ viewerId?: string | null,
39
+ ) {
40
+ const followed = await getFollowedIds(
41
+ viewerId,
42
+ 'note',
43
+ notes.map(({ id }) => id),
44
+ )
45
+ return notes.map((note) => ({ ...note, watching: followed.has(note.id) }))
46
+ }
47
+ ```
48
+
20
49
  > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
21
50
  > It is written to be read by coding agents as much as by people, and is generated from this
22
51
  > package's source — edit `src/index.ts` JSDoc, not this file.
@@ -34,6 +63,23 @@ import { routes, requestHandlerMap } from '@molecule/api-resource-follow'
34
63
  // GET /follow/check/:targetType/:targetId
35
64
  ```
36
65
 
66
+ ```typescript
67
+ import { isFollowing } from '@molecule/api-resource-follow'
68
+
69
+ // The app resolves a username to this public profile before projecting it.
70
+ async function projectProfile(
71
+ profile: { id: string; username: string; bio: string | null; avatar: string | null },
72
+ viewerId: string | null | undefined,
73
+ ) {
74
+ return {
75
+ username: profile.username,
76
+ bio: profile.bio,
77
+ image: profile.avatar,
78
+ following: await isFollowing(viewerId, 'user', profile.id),
79
+ }
80
+ }
81
+ ```
82
+
37
83
  ## Type
38
84
 
39
85
  `resource`
@@ -225,13 +271,17 @@ function getFollowing(userId: string, options?: PaginationOptions): Promise<Pagi
225
271
 
226
272
  #### `isFollowing(followerId, targetType, targetId)`
227
273
 
228
- Checks if a user is following a target.
274
+ Checks if a viewer is following a target. An absent viewer returns false without I/O.
229
275
 
230
276
  ```typescript
231
- function isFollowing(followerId: string, targetType: string, targetId: string): Promise<boolean>
277
+ function isFollowing(
278
+ followerId: string | null | undefined,
279
+ targetType: string,
280
+ targetId: string,
281
+ ): Promise<boolean>
232
282
  ```
233
283
 
234
- - `followerId` — The follower's user ID.
284
+ - `followerId` — The viewer's user ID, or no viewer for public content.
235
285
  - `targetType` — The type of target.
236
286
  - `targetId` — The ID of the target.
237
287
 
package/dist/index.d.ts CHANGED
@@ -8,6 +8,31 @@
8
8
  * deduplicates ids, and does no I/O for an empty page or an absent viewer. It works for
9
9
  * any target type, including documents, topics and users. Use `isFollowing` for one target.
10
10
  *
11
+ * **Custom routes use the same services.** A profile route, username parameter or
12
+ * different response envelope does not require the package's HTTP routes. Resolve
13
+ * the username in the app, then call `follow(viewerId, 'user', profile.id)`,
14
+ * `unfollow(viewerId, 'user', profile.id)` or
15
+ * `isFollowing(viewerId, 'user', profile.id)` and project the profile locally.
16
+ * `isFollowing` accepts `string | null | undefined`; an absent viewer returns
17
+ * `false` without a database read. Mutations still require an authenticated id.
18
+ *
19
+ * These services use the package's `follows` table, with `followerId`, `targetType`
20
+ * and `targetId`. For users, `targetId` is the canonical user id, never the username.
21
+ * A genuinely different relationship schema stays local; these calls do not read a
22
+ * custom `followingId` column or a separate table.
23
+ *
24
+ * ```typescript
25
+ * import { getFollowedIds } from '@molecule/api-resource-follow'
26
+ *
27
+ * export async function projectWatchedNotes(
28
+ * notes: readonly { id: string; title: string }[],
29
+ * viewerId?: string | null,
30
+ * ) {
31
+ * const followed = await getFollowedIds(viewerId, 'note', notes.map(({ id }) => id))
32
+ * return notes.map((note) => ({ ...note, watching: followed.has(note.id) }))
33
+ * }
34
+ * ```
35
+ *
11
36
  * @module
12
37
  * @example
13
38
  * ```typescript
@@ -21,6 +46,24 @@
21
46
  * // GET /follow/check/:targetType/:targetId
22
47
  * ```
23
48
  *
49
+ * @example
50
+ * ```typescript
51
+ * import { isFollowing } from '@molecule/api-resource-follow'
52
+ *
53
+ * // The app resolves a username to this public profile before projecting it.
54
+ * async function projectProfile(
55
+ * profile: { id: string; username: string; bio: string | null; avatar: string | null },
56
+ * viewerId: string | null | undefined,
57
+ * ) {
58
+ * return {
59
+ * username: profile.username,
60
+ * bio: profile.bio,
61
+ * image: profile.avatar,
62
+ * following: await isFollowing(viewerId, 'user', profile.id),
63
+ * }
64
+ * }
65
+ * ```
66
+ *
24
67
  * @remarks
25
68
  * - **List endpoints return a PAGINATED envelope** `{ data, total, limit, offset }`, not a
26
69
  * bare array — read the rows off `result.data` (server). On the client, `unwrapList(res)`
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAEH,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}
package/dist/index.js CHANGED
@@ -8,6 +8,31 @@
8
8
  * deduplicates ids, and does no I/O for an empty page or an absent viewer. It works for
9
9
  * any target type, including documents, topics and users. Use `isFollowing` for one target.
10
10
  *
11
+ * **Custom routes use the same services.** A profile route, username parameter or
12
+ * different response envelope does not require the package's HTTP routes. Resolve
13
+ * the username in the app, then call `follow(viewerId, 'user', profile.id)`,
14
+ * `unfollow(viewerId, 'user', profile.id)` or
15
+ * `isFollowing(viewerId, 'user', profile.id)` and project the profile locally.
16
+ * `isFollowing` accepts `string | null | undefined`; an absent viewer returns
17
+ * `false` without a database read. Mutations still require an authenticated id.
18
+ *
19
+ * These services use the package's `follows` table, with `followerId`, `targetType`
20
+ * and `targetId`. For users, `targetId` is the canonical user id, never the username.
21
+ * A genuinely different relationship schema stays local; these calls do not read a
22
+ * custom `followingId` column or a separate table.
23
+ *
24
+ * ```typescript
25
+ * import { getFollowedIds } from '@molecule/api-resource-follow'
26
+ *
27
+ * export async function projectWatchedNotes(
28
+ * notes: readonly { id: string; title: string }[],
29
+ * viewerId?: string | null,
30
+ * ) {
31
+ * const followed = await getFollowedIds(viewerId, 'note', notes.map(({ id }) => id))
32
+ * return notes.map((note) => ({ ...note, watching: followed.has(note.id) }))
33
+ * }
34
+ * ```
35
+ *
11
36
  * @module
12
37
  * @example
13
38
  * ```typescript
@@ -21,6 +46,24 @@
21
46
  * // GET /follow/check/:targetType/:targetId
22
47
  * ```
23
48
  *
49
+ * @example
50
+ * ```typescript
51
+ * import { isFollowing } from '@molecule/api-resource-follow'
52
+ *
53
+ * // The app resolves a username to this public profile before projecting it.
54
+ * async function projectProfile(
55
+ * profile: { id: string; username: string; bio: string | null; avatar: string | null },
56
+ * viewerId: string | null | undefined,
57
+ * ) {
58
+ * return {
59
+ * username: profile.username,
60
+ * bio: profile.bio,
61
+ * image: profile.avatar,
62
+ * following: await isFollowing(viewerId, 'user', profile.id),
63
+ * }
64
+ * }
65
+ * ```
66
+ *
24
67
  * @remarks
25
68
  * - **List endpoints return a PAGINATED envelope** `{ data, total, limit, offset }`, not a
26
69
  * bare array — read the rows off `result.data` (server). On the client, `unwrapList(res)`
package/dist/service.d.ts CHANGED
@@ -49,14 +49,14 @@ export declare function getFollowers(targetType: string, targetId: string, optio
49
49
  */
50
50
  export declare function getFollowing(userId: string, options?: PaginationOptions): Promise<PaginatedResult<Follow>>;
51
51
  /**
52
- * Checks if a user is following a target.
52
+ * Checks if a viewer is following a target. An absent viewer returns false without I/O.
53
53
  *
54
- * @param followerId - The follower's user ID.
54
+ * @param followerId - The viewer's user ID, or no viewer for public content.
55
55
  * @param targetType - The type of target.
56
56
  * @param targetId - The ID of the target.
57
57
  * @returns `true` if following.
58
58
  */
59
- export declare function isFollowing(followerId: string, targetType: string, targetId: string): Promise<boolean>;
59
+ export declare function isFollowing(followerId: string | null | undefined, targetType: string, targetId: string): Promise<boolean>;
60
60
  /**
61
61
  * Load a viewer's follow state for a collection in one query, rather than one per item.
62
62
  *
@@ -1 +1 @@
1
- {"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAI5E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,MAAM,CAC1B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAoBlC;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAiBlC;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAYtB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK5F;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEvE"}
1
+ {"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAI5E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,MAAM,CAC1B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAoBlC;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAiBlC;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAQlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAYtB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK5F;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEvE"}
package/dist/service.js CHANGED
@@ -97,14 +97,16 @@ export async function getFollowing(userId, options = {}) {
97
97
  return { data, total, limit, offset };
98
98
  }
99
99
  /**
100
- * Checks if a user is following a target.
100
+ * Checks if a viewer is following a target. An absent viewer returns false without I/O.
101
101
  *
102
- * @param followerId - The follower's user ID.
102
+ * @param followerId - The viewer's user ID, or no viewer for public content.
103
103
  * @param targetType - The type of target.
104
104
  * @param targetId - The ID of the target.
105
105
  * @returns `true` if following.
106
106
  */
107
107
  export async function isFollowing(followerId, targetType, targetId) {
108
+ if (!followerId)
109
+ return false;
108
110
  const existing = await findOne(TABLE, [
109
111
  { field: 'followerId', operator: '=', value: followerId },
110
112
  { field: 'targetType', operator: '=', value: targetType },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-resource-follow",
3
- "version": "1.1.1",
3
+ "version": "1.1.3",
4
4
  "description": "Follow/unfollow users or any resource with polymorphic targeting",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",