forge-sql-orm 2.0.20 → 2.0.21

package/README.md

@@ -465,6 +465,20 @@ await forgeSQL.crud().insert(Users, [
     ],
   true
   );
+
+// Insert with sequence (nextVal)
+import { nextVal } from "forge-sql-orm";
+
+const user = {
+  id: nextVal('user_id_seq'),
+  name: "user test",
+  organization_id: 1
+};
+const id = await forgeSQL.modify().insert(appUser, [user]);
+
+// The generated SQL will be:
+// INSERT INTO app_user (id, name, organization_id) 
+// VALUES (NEXTVAL(user_id_seq), ?, ?) -- params: ["user test", 1]
   ```
 
 ### Update Operations
@@ -494,6 +508,41 @@ await forgeSQL.crud().updateFields(
 await forgeSQL.crud().deleteById(1, Users);
 ```
 
+## SQL Utilities
+
+### formatLimitOffset
+
+The `formatLimitOffset` utility function is used to safely insert numeric values directly into SQL queries for LIMIT and OFFSET clauses. This is necessary because Atlassian Forge SQL doesn't support parameterized queries for these clauses.
+
+```typescript
+import { formatLimitOffset } from "forge-sql-orm";
+
+// Example usage in a query
+const result = await forgeSQL
+  .select()
+  .from(orderItem)
+  .orderBy(asc(orderItem.createdAt))
+  .limit(formatLimitOffset(10))
+  .offset(formatLimitOffset(350000));
+
+// The generated SQL will be:
+// SELECT * FROM order_item 
+// ORDER BY created_at ASC 
+// LIMIT 10 
+// OFFSET 350000
+```
+
+**Important Notes:**
+- The function performs type checking to prevent SQL injection
+- It throws an error if the input is not a valid number
+- Use this function instead of direct parameter binding for LIMIT and OFFSET clauses
+- The function is specifically designed to work with Atlassian Forge SQL's limitations
+
+**Security Considerations:**
+- The function includes validation to ensure the input is a valid number
+- This prevents SQL injection by ensuring only numeric values are inserted
+- Always use this function instead of string concatenation for LIMIT and OFFSET values
+
 ## Optimistic Locking
 
 Optimistic locking is a concurrency control mechanism that prevents data conflicts when multiple transactions attempt to update the same record concurrently. Instead of using locks, this technique relies on a version field in your entity models.

package/dist/ForgeSQLORM.js

@@ -269,6 +269,15 @@ function processNullBranches(obj) {
   }
   return allNull ? null : result;
 }
+function formatLimitOffset(limitOrOffset) {
+  if (typeof limitOrOffset !== "number" || isNaN(limitOrOffset)) {
+    throw new Error("limitOrOffset must be a valid number");
+  }
+  return drizzleOrm.sql.raw(`${limitOrOffset}`);
+}
+function nextVal(sequenceName) {
+  return drizzleOrm.sql`SELECT NEXT VALUE FOR ${sequenceName} AS id`;
+}
 class ForgeSQLCrudOperations {
   forgeOperations;
   options;
@@ -1338,6 +1347,7 @@ exports.forgeDriver = forgeDriver;
 exports.forgeSystemTables = forgeSystemTables;
 exports.forgeTimeString = forgeTimeString;
 exports.forgeTimestampString = forgeTimestampString;
+exports.formatLimitOffset = formatLimitOffset;
 exports.generateDropTableStatements = generateDropTableStatements;
 exports.getHttpResponse = getHttpResponse;
 exports.getPrimaryKeys = getPrimaryKeys;
@@ -1346,6 +1356,7 @@ exports.getTables = getTables;
 exports.mapSelectAllFieldsToAlias = mapSelectAllFieldsToAlias;
 exports.mapSelectFieldsWithAlias = mapSelectFieldsWithAlias;
 exports.migrations = migrations;
+exports.nextVal = nextVal;
 exports.parseDateTime = parseDateTime;
 exports.patchDbWithSelectAliased = patchDbWithSelectAliased;
 //# sourceMappingURL=ForgeSQLORM.js.map