chore: add comments

Author: SegaraRai

examples/core-only/server.ts

@@ -1,23 +1,19 @@
-/* A simple example of using Fraci without any ORM. We recommend using an ORM integration, as querying fractional indices manually can be error-prone. */
+/* A simple example of using Fraci without any ORM. We strongly recommend using our ORM integrations, as querying fractional indices manually can be error-prone. */
 
 import { zValidator } from "@hono/zod-validator";
 import { BASE62, fraci, type FractionalIndex } from "fraci";
 import { Hono } from "hono";
 import * as z from "zod";
 
 // Define the type for our fractional index
-type ExampleItemFI = FractionalIndex<
-  typeof BASE62,
-  typeof BASE62,
-  "core.exampleItem.fi"
->;
+type FI = FractionalIndex<typeof BASE62, typeof BASE62, "core.exampleItem.fi">;
 
 // Define the structure of our example item
 interface ExampleItem {
-  id: number;
-  name: string;
-  fi: ExampleItemFI;
-  groupId: number;
+  readonly id: number;
+  readonly name: string;
+  readonly fi: FI;
+  readonly groupId: number;
 }
 
 // In-memory database tables
@@ -119,9 +115,11 @@ const queryUtils = {
 };
 
 // Fraci utility for the example items
+// Implementing this manually is strongly discouraged in a real-world application, as it can be error-prone
+// Instead, use our built-in ORM integrations for your database
 const xfi = {
   // Generate a key between two existing keys
-  generateKeyBetween: (a: ExampleItemFI | null, b: ExampleItemFI | null) => {
+  generateKeyBetween: (a: FI | null, b: FI | null) => {
     return fraciForExampleItem.generateKeyBetween(a, b);
   },
 
@@ -131,13 +129,12 @@ const xfi = {
       where: (item) => item.groupId === where.groupId,
       orderBy: { field: "fi", direction: "asc" },
     });
-
     if (items.length === 0) {
-      return [null, null] as [ExampleItemFI | null, ExampleItemFI | null];
+      return [null, null] as [FI | null, FI | null];
     }
 
     const lastItem = items[items.length - 1] as ExampleItem;
-    return [lastItem.fi, null] as [ExampleItemFI | null, ExampleItemFI | null];
+    return [lastItem.fi, null] as [FI | null, FI | null];
   },
 
   // Get indices for an item before a reference item
@@ -146,7 +143,6 @@ const xfi = {
       where: (item) => item.groupId === where.groupId,
       orderBy: { field: "fi", direction: "asc" },
     });
-
     if (items.length === 0) {
       return null;
     }
@@ -158,8 +154,7 @@ const xfi = {
 
     const prev = refIndex > 0 ? items[refIndex - 1].fi : null;
     const curr = items[refIndex].fi;
-
-    return [prev, curr] as [ExampleItemFI | null, ExampleItemFI | null];
+    return [prev, curr] as [FI | null, FI | null];
   },
 
   // Get indices for an item after a reference item
@@ -168,7 +163,6 @@ const xfi = {
       where: (item) => item.groupId === where.groupId,
       orderBy: { field: "fi", direction: "asc" },
     });
-
     if (items.length === 0) {
       return null;
     }
@@ -180,8 +174,7 @@ const xfi = {
 
     const curr = items[refIndex].fi;
     const next = refIndex < items.length - 1 ? items[refIndex + 1].fi : null;
-
-    return [curr, next] as [ExampleItemFI | null, ExampleItemFI | null];
+    return [curr, next] as [FI | null, FI | null];
   },
 
   // Check if an error is an index conflict error
@@ -194,7 +187,9 @@ const xfi = {
 };
 
 // Function to check for index conflicts
-function checkIndexConflict(groupId: number, fi: ExampleItemFI): boolean {
+// Implementing this manually is strongly discouraged in a real-world application, as it can be error-prone
+// Instead, use the built-in unique constraint handling provided by your database or ORM
+function checkIndexConflict(groupId: number, fi: FI): boolean {
   return exampleItems.some(
     (item) => item.groupId === groupId && item.fi === fi
   );

examples/rolldown.config.ts

@@ -41,7 +41,7 @@ export default defineConfig(
             },
             {
               name: "others",
-              priority: 10,
+              priority: 100,
             },
           ],
         },
@@ -50,6 +50,12 @@ export default defineConfig(
         {
           name: "show-size",
           async generateBundle(_options, bundle) {
+            this.emitFile({
+              fileName: `__${entrypoint}__`,
+              type: "asset",
+              source: "",
+            });
+
             const fraciBundle = bundle["fraci.js"];
             if (fraciBundle?.type !== "chunk") {
               return;