@molecule/api-resource-comment 1.0.5 → 1.1.0

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-08-04T01:49:10.106Z
+Generated: 2026-10-15T14:22:29.350Z
 -->
 
 # @molecule/api-resource-comment
@@ -127,6 +127,19 @@ interface UpdateCommentInput {
 }
 ```
 
+### Types
+
+#### `NumberedComment`
+
+A comment together with its sequential number.
+
+```typescript
+type NumberedComment = Comment & {
+  /** The comment's sequential integer number (1, 2, 3, …). */
+  number: number
+}
+```
+
 ### Functions
 
 #### `commentCount(req, res)`
@@ -140,6 +153,19 @@ function commentCount(req: MoleculeRequest, res: MoleculeResponse): Promise<void
 - `req` — The request with `resourceType` and `resourceId` params.
 - `res` — The response object.
 
+#### `commentNumbers(commentIds)`
+
+The numbers of the given comments, for listing them with their numbers.
+Comments without a number are left out of the map.
+
+```typescript
+function commentNumbers(commentIds: readonly string[]): Promise<Map<string, number>>
+```
+
+- `commentIds` — The comments' UUIDs.
+
+**Returns:** Each numbered comment's UUID mapped to its number.
+
 #### `create(req, res)`
 
 Creates a new comment on a resource.
@@ -171,6 +197,26 @@ function createComment(
 
 **Returns:** The created comment.
 
+#### `createNumberedComment(resourceType, resourceId, userId, data)`
+
+Creates a comment and its number together: both are written, or neither.
+
+```typescript
+function createNumberedComment(
+  resourceType: string,
+  resourceId: string,
+  userId: string,
+  data: CreateCommentInput,
+): Promise<NumberedComment>
+```
+
+- `resourceType` — The type of resource being commented on.
+- `resourceId` — The ID of the resource being commented on.
+- `userId` — The ID of the commenting user.
+- `data` — The comment creation input.
+
+**Returns:** The created comment with its number.
+
 #### `del(req, res)`
 
 Deletes a comment. Only the comment owner can delete.
@@ -207,6 +253,18 @@ function getCommentById(commentId: string): Promise<Comment | null>
 
 **Returns:** The comment or `null` if not found.
 
+#### `getCommentByNumber(number)`
+
+The comment a number belongs to.
+
+```typescript
+function getCommentByNumber(number: number): Promise<NumberedComment | null>
+```
+
+- `number` — The comment's sequential number.
+
+**Returns:** The comment with its number, or `null` when no comment has it.
+
 #### `getCommentCount(resourceType, resourceId)`
 
 Returns the total number of comments on a resource (including replies).
@@ -266,6 +324,19 @@ function list(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
 - `req` — The request with `resourceType` and `resourceId` params.
 - `res` — The response object.
 
+#### `numberComment(commentId)`
+
+The comment's number, allocating the next one when it has none. Numbers are
+unique and increase.
+
+```typescript
+function numberComment(commentId: string): Promise<number>
+```
+
+- `commentId` — The comment's UUID.
+
+**Returns:** Its sequential number.
+
 #### `read(req, res)`
 
 Retrieves a single comment by ID.
@@ -403,7 +474,7 @@ const updateCommentSchema: z.ZodObject<{ body: z.ZodString }, z.core.$strip>
 
 Peer dependencies:
 
-- `@molecule/api-database` ^1.0.1
+- `@molecule/api-database` ^1.1.0
 - `@molecule/api-i18n` ^1.0.1
 - `@molecule/api-logger` ^1.0.1
 - `@molecule/api-resource` ^1.0.1
@@ -425,6 +496,10 @@ Peer dependencies:
 - **Migration required.** `src/__setup__/comments.sql` ships with this package
   and must exist in the target database before use (scaffolded apps apply it
   automatically; existing apps must apply it first).
+- **Integer comment ids (RealWorld's `comment.id`, most public API specs):** keep the
+  UUID and give each comment a sequential number — `createNumberedComment()` creates both
+  in one transaction, `getCommentByNumber(n)` finds it, `commentNumbers(ids)` maps a list.
+  Apply `src/__setup__/comment_numbers.sql` too. Never build your own id-mapping table.
 - **Reads are PUBLIC by default.** `list`, `read`, `replies`, and `count` ship
   with no auth middleware (comment threads on public content). If the
   commented resources are private in your app, add an authorizer that checks

package/dist/index.d.ts

@@ -28,6 +28,10 @@
  * - **Migration required.** `src/__setup__/comments.sql` ships with this package
  *   and must exist in the target database before use (scaffolded apps apply it
  *   automatically; existing apps must apply it first).
+ * - **Integer comment ids (RealWorld's `comment.id`, most public API specs):** keep the
+ *   UUID and give each comment a sequential number — `createNumberedComment()` creates both
+ *   in one transaction, `getCommentByNumber(n)` finds it, `commentNumbers(ids)` maps a list.
+ *   Apply `src/__setup__/comment_numbers.sql` too. Never build your own id-mapping table.
  * - **Reads are PUBLIC by default.** `list`, `read`, `replies`, and `count` ship
  *   with no auth middleware (comment threads on public content). If the
  *   commented resources are private in your app, add an authorizer that checks
@@ -60,6 +64,7 @@
 export * from './authorizers/index.js';
 export * from './browser-guard.js';
 export * from './handlers/index.js';
+export * from './numbers.js';
 export * from './requestHandlerMap.js';
 export * from './routes.js';
 export * from './service.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;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;AAC1B,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;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

@@ -28,6 +28,10 @@
  * - **Migration required.** `src/__setup__/comments.sql` ships with this package
  *   and must exist in the target database before use (scaffolded apps apply it
  *   automatically; existing apps must apply it first).
+ * - **Integer comment ids (RealWorld's `comment.id`, most public API specs):** keep the
+ *   UUID and give each comment a sequential number — `createNumberedComment()` creates both
+ *   in one transaction, `getCommentByNumber(n)` finds it, `commentNumbers(ids)` maps a list.
+ *   Apply `src/__setup__/comment_numbers.sql` too. Never build your own id-mapping table.
  * - **Reads are PUBLIC by default.** `list`, `read`, `replies`, and `count` ship
  *   with no auth middleware (comment threads on public content). If the
  *   commented resources are private in your app, add an authorizer that checks
@@ -60,6 +64,7 @@
 export * from './authorizers/index.js';
 export * from './browser-guard.js';
 export * from './handlers/index.js';
+export * from './numbers.js';
 export * from './requestHandlerMap.js';
 export * from './routes.js';
 export * from './service.js';

package/dist/numbers.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Sequential integer numbers for comments, for APIs whose clients address a
+ * comment by an integer (RealWorld's `comment.id` is one; so are most public
+ * API specs). The comment keeps its UUID; the number lives in
+ * `comment_numbers` and is allocated once, at most one per comment.
+ *
+ * @module
+ */
+import type { Comment, CreateCommentInput } from './types.js';
+/** A comment together with its sequential number. */
+export type NumberedComment = Comment & {
+    /** The comment's sequential integer number (1, 2, 3, …). */
+    number: number;
+};
+/**
+ * The comment's number, allocating the next one when it has none. Numbers are
+ * unique and increase.
+ *
+ * @param commentId - The comment's UUID.
+ * @returns Its sequential number.
+ * @throws {Error} When no number could be allocated after several attempts.
+ */
+export declare function numberComment(commentId: string): Promise<number>;
+/**
+ * Creates a comment and its number together: both are written, or neither.
+ *
+ * @param resourceType - The type of resource being commented on.
+ * @param resourceId - The ID of the resource being commented on.
+ * @param userId - The ID of the commenting user.
+ * @param data - The comment creation input.
+ * @returns The created comment with its number.
+ */
+export declare function createNumberedComment(resourceType: string, resourceId: string, userId: string, data: CreateCommentInput): Promise<NumberedComment>;
+/**
+ * The comment a number belongs to.
+ *
+ * @param number - The comment's sequential number.
+ * @returns The comment with its number, or `null` when no comment has it.
+ */
+export declare function getCommentByNumber(number: number): Promise<NumberedComment | null>;
+/**
+ * The numbers of the given comments, for listing them with their numbers.
+ * Comments without a number are left out of the map.
+ *
+ * @param commentIds - The comments' UUIDs.
+ * @returns Each numbered comment's UUID mapped to its number.
+ */
+export declare function commentNumbers(commentIds: readonly string[]): Promise<Map<string, number>>;
+//# sourceMappingURL=numbers.d.ts.map

package/dist/numbers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../src/numbers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAI7D,qDAAqD;AACrD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG;IACtC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAuDD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtE;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAK1B;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAQxF;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMhG"}

package/dist/numbers.js

@@ -0,0 +1,117 @@
+/**
+ * Sequential integer numbers for comments, for APIs whose clients address a
+ * comment by an integer (RealWorld's `comment.id` is one; so are most public
+ * API specs). The comment keeps its UUID; the number lives in
+ * `comment_numbers` and is allocated once, at most one per comment.
+ *
+ * @module
+ */
+import { create as dbCreate, findMany, findOne, getActiveTransaction, withTransaction, } from '@molecule/api-database';
+import { createComment, getCommentById } from './service.js';
+const NUMBERS = 'comment_numbers';
+/** How many times the work is redone when a concurrent writer took the number first. */
+const MAX_ATTEMPTS = 5;
+/**
+ * Runs `work` in its own transaction, again when it fails: a concurrent
+ * writer that took the same number fails the unique key, and the next
+ * attempt allocates the next number. Inside a caller's transaction a failed
+ * statement can poison it (Postgres), so there the work runs once and the
+ * caller decides.
+ *
+ * @param what - What is being numbered, for the error.
+ * @param work - The allocation.
+ * @returns What `work` resolves to.
+ */
+async function withNumberRetry(what, work) {
+    if (getActiveTransaction())
+        return work();
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await withTransaction(work);
+        }
+        catch (error) {
+            if (attempt >= MAX_ATTEMPTS)
+                throw new Error(`Could not number ${what}`, { cause: error });
+            // Rolled back; a concurrent writer most likely took the number (its
+            // unique key failed). The next attempt reads the new highest number.
+        }
+    }
+}
+/**
+ * Allocates the next number for a comment that has none (no transaction of its own).
+ *
+ * @param commentId - The comment's UUID.
+ * @returns Its number.
+ */
+async function allocate(commentId) {
+    const existing = await findOne(NUMBERS, [
+        { field: 'commentId', operator: '=', value: commentId },
+    ]);
+    if (existing)
+        return Number(existing.number);
+    const [last] = await findMany(NUMBERS, {
+        orderBy: [{ field: 'number', direction: 'desc' }],
+        limit: 1,
+    });
+    const number = (last ? Number(last.number) : 0) + 1;
+    await dbCreate(NUMBERS, { number, commentId });
+    return number;
+}
+/**
+ * The comment's number, allocating the next one when it has none. Numbers are
+ * unique and increase.
+ *
+ * @param commentId - The comment's UUID.
+ * @returns Its sequential number.
+ * @throws {Error} When no number could be allocated after several attempts.
+ */
+export async function numberComment(commentId) {
+    return withNumberRetry(`comment ${commentId}`, () => allocate(commentId));
+}
+/**
+ * Creates a comment and its number together: both are written, or neither.
+ *
+ * @param resourceType - The type of resource being commented on.
+ * @param resourceId - The ID of the resource being commented on.
+ * @param userId - The ID of the commenting user.
+ * @param data - The comment creation input.
+ * @returns The created comment with its number.
+ */
+export async function createNumberedComment(resourceType, resourceId, userId, data) {
+    return withNumberRetry('a new comment', async () => {
+        const comment = await createComment(resourceType, resourceId, userId, data);
+        return { ...comment, number: await allocate(comment.id) };
+    });
+}
+/**
+ * The comment a number belongs to.
+ *
+ * @param number - The comment's sequential number.
+ * @returns The comment with its number, or `null` when no comment has it.
+ */
+export async function getCommentByNumber(number) {
+    if (!Number.isInteger(number) || number < 1)
+        return null;
+    const row = await findOne(NUMBERS, [
+        { field: 'number', operator: '=', value: number },
+    ]);
+    if (!row)
+        return null;
+    const comment = await getCommentById(row.commentId);
+    return comment ? { ...comment, number: Number(row.number) } : null;
+}
+/**
+ * The numbers of the given comments, for listing them with their numbers.
+ * Comments without a number are left out of the map.
+ *
+ * @param commentIds - The comments' UUIDs.
+ * @returns Each numbered comment's UUID mapped to its number.
+ */
+export async function commentNumbers(commentIds) {
+    if (commentIds.length === 0)
+        return new Map();
+    const rows = await findMany(NUMBERS, {
+        where: [{ field: 'commentId', operator: 'in', value: [...commentIds] }],
+    });
+    return new Map(rows.map((r) => [r.commentId, Number(r.number)]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-resource-comment",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Threaded comments on any resource with polymorphic attachment and pagination",
   "type": "module",
   "main": "dist/index.js",
@@ -29,13 +29,15 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
+    "@molecule/api-database": "1.1.0",
+    "@molecule/api-database-sqlite": "1.1.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.11",
     "zod": "4.4.3"
   },
   "peerDependencies": {
-    "@molecule/api-database": "^1.0.1",
+    "@molecule/api-database": "^1.1.0",
     "@molecule/api-i18n": "^1.0.1",
     "@molecule/api-logger": "^1.0.1",
     "@molecule/api-resource": "^1.0.1",

package/src/__setup__/comment_numbers.sql

@@ -0,0 +1,8 @@
+-- Sequential integer numbers for comments, for APIs whose clients address a
+-- comment by an integer id (RealWorld's `comment.id` is an integer). Opt-in:
+-- written by numberComment() / createNumberedComment(); comments without a
+-- number keep working by their UUID.
+CREATE TABLE IF NOT EXISTS "comment_numbers" (
+  "number" INTEGER PRIMARY KEY,
+  "commentId" UUID NOT NULL UNIQUE REFERENCES "comments"("id") ON DELETE CASCADE
+);