@molecule/api-resource-comment 1.2.4 → 1.2.5

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-31T12:45:29.246Z
+Generated: 2026-11-09T22:47:15.896Z
 -->
 
 # @molecule/api-resource-comment
@@ -60,6 +60,8 @@ A comment attached to a resource, with optional threading via `parentId`.
 interface Comment {
   /** Unique comment identifier. */
   id: string
+  /** Stable integer identity on creates and paginated reads; absent on unnumbered imports. */
+  number?: number
   /** The type of resource this comment is attached to (e.g. 'project', 'post'). */
   resourceType: string
   /** The ID of the resource this comment is attached to. */
@@ -331,9 +333,10 @@ function createComment(
 Retrieves paginated comments for a resource, ordered by creation date descending.
 Only returns top-level comments (no replies).
 
-The rows carry each comment's UUID `id`; for an API that addresses comments by an
-integer, map a page's ids with `commentNumbers()` — every comment `createComment()`
-wrote is in that map, and a missing entry (a raw insert) is never `0`.
+The rows carry each comment's UUID `id` and its stable `number` when numbered.
+An integer-addressed API returns that number as its external id, never the page
+index. A raw import may have no number; call `numberComment(id)` explicitly
+before exposing it through an integer-addressed API.
 
 ```typescript
 function getCommentsByResource(
@@ -394,7 +397,8 @@ function deleteComment(commentId: string, userId: string): Promise<boolean>
 
 #### `getReplies(commentId, options)`
 
-Retrieves paginated replies to a comment, ordered by creation date ascending.
+Retrieves paginated replies to a comment, ordered by creation date ascending,
+with each reply's stable `number` when numbered, like `getCommentsByResource`.
 
 ```typescript
 function getReplies(
@@ -535,6 +539,8 @@ Peer dependencies:
 - **Integer comment ids — every comment is numbered by default.** `createComment()`
   writes the comment and its sequential `number` (1, 2, 3, …) together and returns both;
   `createNumberedComment()` is the same create under the name an integer-id API reads best.
+  Paginated comments and replies also carry that stable `number`. Never derive an
+  identity from the page index: sorting, pagination and deletion change positions.
   For an API whose clients address a comment by a stable integer,
   return `number` as the id and read it back with
   `getCommentByNumber(n)` — never hand-build an id from the UUID, and never read a missing

package/dist/index.d.ts

@@ -40,6 +40,8 @@
  * - **Integer comment ids — every comment is numbered by default.** `createComment()`
  *   writes the comment and its sequential `number` (1, 2, 3, …) together and returns both;
  *   `createNumberedComment()` is the same create under the name an integer-id API reads best.
+ *   Paginated comments and replies also carry that stable `number`. Never derive an
+ *   identity from the page index: sorting, pagination and deletion change positions.
  *   For an API whose clients address a comment by a stable integer,
  *   return `number` as the id and read it back with
  *   `getCommentByNumber(n)` — never hand-build an id from the UUID, and never read a missing

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,cAAc,CAAA;AAC5B,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AAEH,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,cAAc,CAAA;AAC5B,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}

package/dist/index.js

@@ -40,6 +40,8 @@
  * - **Integer comment ids — every comment is numbered by default.** `createComment()`
  *   writes the comment and its sequential `number` (1, 2, 3, …) together and returns both;
  *   `createNumberedComment()` is the same create under the name an integer-id API reads best.
+ *   Paginated comments and replies also carry that stable `number`. Never derive an
+ *   identity from the page index: sorting, pagination and deletion change positions.
  *   For an API whose clients address a comment by a stable integer,
  *   return `number` as the id and read it back with
  *   `getCommentByNumber(n)` — never hand-build an id from the UUID, and never read a missing

package/dist/service.d.ts

@@ -35,9 +35,10 @@ export declare function createComment(resourceType: string, resourceId: string,
  * Retrieves paginated comments for a resource, ordered by creation date descending.
  * Only returns top-level comments (no replies).
  *
- * The rows carry each comment's UUID `id`; for an API that addresses comments by an
- * integer, map a page's ids with `commentNumbers()` — every comment `createComment()`
- * wrote is in that map, and a missing entry (a raw insert) is never `0`.
+ * The rows carry each comment's UUID `id` and its stable `number` when numbered.
+ * An integer-addressed API returns that number as its external id, never the page
+ * index. A raw import may have no number; call `numberComment(id)` explicitly
+ * before exposing it through an integer-addressed API.
  *
  * @param resourceType - The type of resource.
  * @param resourceId - The ID of the resource.
@@ -74,7 +75,8 @@ export declare function updateComment(commentId: string, userId: string, data: U
  */
 export declare function deleteComment(commentId: string, userId: string): Promise<boolean>;
 /**
- * Retrieves paginated replies to a comment, ordered by creation date ascending.
+ * Retrieves paginated replies to a comment, ordered by creation date ascending,
+ * with each reply's stable `number` when numbered, like `getCommentsByResource`.
  *
  * @param commentId - The parent comment ID.
  * @param options - Pagination options.

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EACV,OAAO,EACP,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAInB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAyB1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAqBnC;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAE/E;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAczB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMvF;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAiBnC;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK/F"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EACV,OAAO,EACP,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAanB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAyB1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAqBnC;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAE/E;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAczB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMvF;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAiBnC;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK/F"}

package/dist/service.js

@@ -7,8 +7,16 @@
  * @module
  */
 import { count, create as dbCreate, deleteById, findById, findMany, updateById, } from '@molecule/api-database';
-import { allocateCommentNumber } from './numbering.js';
+import { allocateCommentNumber, numbersForComments } from './numbering.js';
 const TABLE = 'comments';
+/** Keep a page's stable integer identities beside its UUIDs without allocating on read. */
+async function withNumbers(comments) {
+    const numbers = await numbersForComments(comments.map((comment) => comment.id));
+    return comments.map((comment) => {
+        const number = numbers.get(comment.id);
+        return number === undefined ? comment : { ...comment, number };
+    });
+}
 /**
  * Creates a new comment on a resource, with its sequential number.
  *
@@ -59,9 +67,10 @@ export async function createComment(resourceType, resourceId, userId, data) {
  * Retrieves paginated comments for a resource, ordered by creation date descending.
  * Only returns top-level comments (no replies).
  *
- * The rows carry each comment's UUID `id`; for an API that addresses comments by an
- * integer, map a page's ids with `commentNumbers()` — every comment `createComment()`
- * wrote is in that map, and a missing entry (a raw insert) is never `0`.
+ * The rows carry each comment's UUID `id` and its stable `number` when numbered.
+ * An integer-addressed API returns that number as its external id, never the page
+ * index. A raw import may have no number; call `numberComment(id)` explicitly
+ * before exposing it through an integer-addressed API.
  *
  * @param resourceType - The type of resource.
  * @param resourceId - The ID of the resource.
@@ -85,7 +94,7 @@ export async function getCommentsByResource(resourceType, resourceId, options =
         }),
         count(TABLE, where),
     ]);
-    return { data, total, limit, offset };
+    return { data: await withNumbers(data), total, limit, offset };
 }
 /**
  * Retrieves a single comment by ID.
@@ -136,7 +145,8 @@ export async function deleteComment(commentId, userId) {
     return true;
 }
 /**
- * Retrieves paginated replies to a comment, ordered by creation date ascending.
+ * Retrieves paginated replies to a comment, ordered by creation date ascending,
+ * with each reply's stable `number` when numbered, like `getCommentsByResource`.
  *
  * @param commentId - The parent comment ID.
  * @param options - Pagination options.
@@ -155,7 +165,7 @@ export async function getReplies(commentId, options = {}) {
         }),
         count(TABLE, where),
     ]);
-    return { data, total, limit, offset };
+    return { data: await withNumbers(data), total, limit, offset };
 }
 /**
  * Returns the total number of comments on a resource (including replies).

package/dist/types.d.ts

@@ -12,6 +12,8 @@
 export interface Comment {
     /** Unique comment identifier. */
     id: string;
+    /** Stable integer identity on creates and paginated reads; absent on unnumbered imports. */
+    number?: number;
     /** The type of resource this comment is attached to (e.g. 'project', 'post'). */
     resourceType: string;
     /** The ID of the resource this comment is attached to. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,oFAAoF;IACpF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,6CAA6C;IAC7C,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,oFAAoF;IACpF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,6CAA6C;IAC7C,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;CACf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-resource-comment",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "Threaded comments on any resource with polymorphic attachment and pagination",
   "type": "module",
   "main": "dist/index.js",