@molecule/api-resource-follow 1.0.7 → 1.0.9

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,20 +3,20 @@ 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-10-16T05:33:21.397Z
6
+ Generated: 2026-10-21T18:17:13.993Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-resource-follow
10
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
11
  Follow/unfollow resource for molecule.dev.
16
12
 
17
13
  Polymorphic follow system for users or any resource type. Supports
18
14
  followers list, following list, and follow status checks.
19
15
 
16
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
17
+ > It is written to be read by coding agents as much as by people, and is generated from this
18
+ > package's source — edit `src/index.ts` JSDoc, not this file.
19
+
20
20
  ## Quick Start
21
21
 
22
22
  ```typescript
@@ -156,13 +156,23 @@ function checkFollowing(req: MoleculeRequest, res: MoleculeResponse): Promise<vo
156
156
 
157
157
  Creates a follow relationship. Idempotent — returns existing follow if already following.
158
158
 
159
+ `targetId` is stored exactly as supplied: the package does not resolve a
160
+ username or display handle to an id, and does not require the target to
161
+ exist. For `targetType` `'user'`, pass the target's user `id` — the same
162
+ identity the rest of the app keys that user's rows by (an app using
163
+ `@molecule/api-resource-article`'s feed stores that id in `articles.authorId`,
164
+ which the feed matches against `targetId`); a route that receives a username
165
+ resolves it first. For any other `targetType`, the canonical id is whatever
166
+ the app's own reader of that resource uses. Pass the SAME value to
167
+ `unfollow` and `isFollowing`, or those calls target a different follow.
168
+
159
169
  ```typescript
160
170
  function follow(followerId: string, targetType: string, targetId: string): Promise<Follow>
161
171
  ```
162
172
 
163
173
  - `followerId` — The ID of the follower.
164
174
  - `targetType` — The type of target being followed.
165
- - `targetId` — The ID of the target being followed.
175
+ - `targetId` — The target's canonical id. For `'user'`, the user id, not a username or display handle.
166
176
 
167
177
  **Returns:** The created or existing follow.
168
178
 
@@ -325,7 +335,10 @@ Peer dependencies:
325
335
  from `@molecule/app-http` normalizes this envelope (pass it the whole HttpResponse), so
326
336
  the rows come back; reading the response as a bare array — or `res.data` alone (which is
327
337
  the envelope) — yields an EMPTY list.
328
- Table: `src/__setup__/follows.sql` creates the single `follows` table. An
338
+ A scaffold that lists this package already has this table: its `__setup__` SQL is copied
339
+ into the app at create time and replayed on every boot, so do not copy it into
340
+ `api/migrations/` yourself — only a package added after the scaffold needs that.
341
+ `src/__setup__/follows.sql` creates the single `follows` table. An
329
342
  mlcl-scaffolded API replays `__setup__/*.sql` on migrate (a `CREATE TABLE IF NOT EXISTS`, so a table the app's own migrations already create keeps only its own columns: ALTER in the ones it lacks);
330
343
  anywhere else run it once — nothing at runtime creates it.
331
344
 
package/dist/index.d.ts CHANGED
@@ -23,7 +23,10 @@
23
23
  * from `@molecule/app-http` normalizes this envelope (pass it the whole HttpResponse), so
24
24
  * the rows come back; reading the response as a bare array — or `res.data` alone (which is
25
25
  * the envelope) — yields an EMPTY list.
26
- * Table: `src/__setup__/follows.sql` creates the single `follows` table. An
26
+ * A scaffold that lists this package already has this table: its `__setup__` SQL is copied
27
+ * into the app at create time and replayed on every boot, so do not copy it into
28
+ * `api/migrations/` yourself — only a package added after the scaffold needs that.
29
+ * `src/__setup__/follows.sql` creates the single `follows` table. An
27
30
  * mlcl-scaffolded API replays `__setup__/*.sql` on migrate (a `CREATE TABLE IF NOT EXISTS`, so a table the app's own migrations already create keeps only its own columns: ALTER in the ones it lacks);
28
31
  * anywhere else run it once — nothing at runtime creates it.
29
32
  *
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;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
@@ -23,7 +23,10 @@
23
23
  * from `@molecule/app-http` normalizes this envelope (pass it the whole HttpResponse), so
24
24
  * the rows come back; reading the response as a bare array — or `res.data` alone (which is
25
25
  * the envelope) — yields an EMPTY list.
26
- * Table: `src/__setup__/follows.sql` creates the single `follows` table. An
26
+ * A scaffold that lists this package already has this table: its `__setup__` SQL is copied
27
+ * into the app at create time and replayed on every boot, so do not copy it into
28
+ * `api/migrations/` yourself — only a package added after the scaffold needs that.
29
+ * `src/__setup__/follows.sql` creates the single `follows` table. An
27
30
  * mlcl-scaffolded API replays `__setup__/*.sql` on migrate (a `CREATE TABLE IF NOT EXISTS`, so a table the app's own migrations already create keeps only its own columns: ALTER in the ones it lacks);
28
31
  * anywhere else run it once — nothing at runtime creates it.
29
32
  *
package/dist/service.d.ts CHANGED
@@ -7,9 +7,19 @@ import type { Follow, PaginatedResult, PaginationOptions } from './types.js';
7
7
  /**
8
8
  * Creates a follow relationship. Idempotent — returns existing follow if already following.
9
9
  *
10
+ * `targetId` is stored exactly as supplied: the package does not resolve a
11
+ * username or display handle to an id, and does not require the target to
12
+ * exist. For `targetType` `'user'`, pass the target's user `id` — the same
13
+ * identity the rest of the app keys that user's rows by (an app using
14
+ * `@molecule/api-resource-article`'s feed stores that id in `articles.authorId`,
15
+ * which the feed matches against `targetId`); a route that receives a username
16
+ * resolves it first. For any other `targetType`, the canonical id is whatever
17
+ * the app's own reader of that resource uses. Pass the SAME value to
18
+ * `unfollow` and `isFollowing`, or those calls target a different follow.
19
+ *
10
20
  * @param followerId - The ID of the follower.
11
21
  * @param targetType - The type of target being followed.
12
- * @param targetId - The ID of the target being followed.
22
+ * @param targetId - The target's canonical id. For `'user'`, the user id, not a username or display handle.
13
23
  * @returns The created or existing follow.
14
24
  */
15
25
  export declare function follow(followerId: string, targetType: string, targetId: string): Promise<Follow>;
@@ -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;;;;;;;GAOG;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;;;;;;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,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAOlB;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
@@ -8,9 +8,19 @@ const TABLE = 'follows';
8
8
  /**
9
9
  * Creates a follow relationship. Idempotent — returns existing follow if already following.
10
10
  *
11
+ * `targetId` is stored exactly as supplied: the package does not resolve a
12
+ * username or display handle to an id, and does not require the target to
13
+ * exist. For `targetType` `'user'`, pass the target's user `id` — the same
14
+ * identity the rest of the app keys that user's rows by (an app using
15
+ * `@molecule/api-resource-article`'s feed stores that id in `articles.authorId`,
16
+ * which the feed matches against `targetId`); a route that receives a username
17
+ * resolves it first. For any other `targetType`, the canonical id is whatever
18
+ * the app's own reader of that resource uses. Pass the SAME value to
19
+ * `unfollow` and `isFollowing`, or those calls target a different follow.
20
+ *
11
21
  * @param followerId - The ID of the follower.
12
22
  * @param targetType - The type of target being followed.
13
- * @param targetId - The ID of the target being followed.
23
+ * @param targetId - The target's canonical id. For `'user'`, the user id, not a username or display handle.
14
24
  * @returns The created or existing follow.
15
25
  */
16
26
  export async function follow(followerId, targetType, targetId) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-resource-follow",
3
- "version": "1.0.7",
3
+ "version": "1.0.9",
4
4
  "description": "Follow/unfollow users or any resource with polymorphic targeting",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",