@molecule/api-resource-follow 1.1.1 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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-17T00:12:45.687Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-resource-follow
@@ -17,6 +17,19 @@ 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
+
20
33
  > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
21
34
  > It is written to be read by coding agents as much as by people, and is generated from this
22
35
  > package's source — edit `src/index.ts` JSDoc, not this file.
@@ -34,6 +47,23 @@ import { routes, requestHandlerMap } from '@molecule/api-resource-follow'
34
47
  // GET /follow/check/:targetType/:targetId
35
48
  ```
36
49
 
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
+
37
67
  ## Type
38
68
 
39
69
  `resource`
@@ -225,13 +255,17 @@ function getFollowing(userId: string, options?: PaginationOptions): Promise<Pagi
225
255
 
226
256
  #### `isFollowing(followerId, targetType, targetId)`
227
257
 
228
- Checks if a user is following a target.
258
+ Checks if a viewer is following a target. An absent viewer returns false without I/O.
229
259
 
230
260
  ```typescript
231
- function isFollowing(followerId: string, targetType: string, targetId: string): Promise<boolean>
261
+ function isFollowing(
262
+ followerId: string | null | undefined,
263
+ targetType: string,
264
+ targetId: string,
265
+ ): Promise<boolean>
232
266
  ```
233
267
 
234
- - `followerId` — The follower's user ID.
268
+ - `followerId` — The viewer's user ID, or no viewer for public content.
235
269
  - `targetType` — The type of target.
236
270
  - `targetId` — The ID of the target.
237
271
 
package/dist/index.d.ts CHANGED
@@ -8,6 +8,19 @@
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
+ *
11
24
  * @module
12
25
  * @example
13
26
  * ```typescript
@@ -21,6 +34,24 @@
21
34
  * // GET /follow/check/:targetType/:targetId
22
35
  * ```
23
36
  *
37
+ * @example
38
+ * ```typescript
39
+ * import { isFollowing } from '@molecule/api-resource-follow'
40
+ *
41
+ * // The app resolves a username to this public profile before projecting it.
42
+ * async function projectProfile(
43
+ * profile: { id: string; username: string; bio: string | null; avatar: string | null },
44
+ * viewerId: string | null | undefined,
45
+ * ) {
46
+ * return {
47
+ * username: profile.username,
48
+ * bio: profile.bio,
49
+ * image: profile.avatar,
50
+ * following: await isFollowing(viewerId, 'user', profile.id),
51
+ * }
52
+ * }
53
+ * ```
54
+ *
24
55
  * @remarks
25
56
  * - **List endpoints return a PAGINATED envelope** `{ data, total, limit, offset }`, not a
26
57
  * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;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,19 @@
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
+ *
11
24
  * @module
12
25
  * @example
13
26
  * ```typescript
@@ -21,6 +34,24 @@
21
34
  * // GET /follow/check/:targetType/:targetId
22
35
  * ```
23
36
  *
37
+ * @example
38
+ * ```typescript
39
+ * import { isFollowing } from '@molecule/api-resource-follow'
40
+ *
41
+ * // The app resolves a username to this public profile before projecting it.
42
+ * async function projectProfile(
43
+ * profile: { id: string; username: string; bio: string | null; avatar: string | null },
44
+ * viewerId: string | null | undefined,
45
+ * ) {
46
+ * return {
47
+ * username: profile.username,
48
+ * bio: profile.bio,
49
+ * image: profile.avatar,
50
+ * following: await isFollowing(viewerId, 'user', profile.id),
51
+ * }
52
+ * }
53
+ * ```
54
+ *
24
55
  * @remarks
25
56
  * - **List endpoints return a PAGINATED envelope** `{ data, total, limit, offset }`, not a
26
57
  * 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.2",
4
4
  "description": "Follow/unfollow users or any resource with polymorphic targeting",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",