doc: formatting IDs

docs/orm/benchmark.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 18
+sidebar_position: 19
 description: ORM performance benchmark
 ---
 

docs/orm/errors.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 16
+sidebar_position: 17
 description: ORM Errors
 ---
 

docs/orm/formatting-ids.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 13
+description: Formatting IDs in ZModel
+---
+
+import ZenStackVsPrisma from '../_components/ZenStackVsPrisma';
+
+# Formatting IDs
+
+<ZenStackVsPrisma>
+ID formatting is a ZModel feature and doesn't exist in Prisma.
+</ZenStackVsPrisma>
+
+Prefixing and suffixing model IDs is becoming more common in database design, usually by including the model name in the generated ID. This aids debugging and troubleshooting because developers can easily spot when an ID of one model has been passed to a service expecting an ID of another model.
+
+ZenStack supports this pattern via a new `format` parameter added to every ID function. Simply pass a format string to the function, and it will replace the `%s` sequence with the generated ID.
+
+:::info
+* Not all ID functions have the same signature. See [the function reference](../reference/zmodel/function#predefined-functions) for more details.
+* It is considered an error if the format string does not contain `%s`
+:::
+
+```zmodel title='/schema.zmodel'
+model User {
+    id String @id @default(uuid(7, 'user_%s'))
+    ...
+}
+```
+
+In the future, this pattern may be implemented via the `@default` attribute directly, which would allow IDs to be generated via complex expressions rather than string formatting.

docs/orm/inferred-types.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 15
+sidebar_position: 16
 description: TypeScript types derived from the ZModel schema
 ---
 

docs/orm/logging.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 14
+sidebar_position: 15
 description: Setup logging
 ---
 

docs/orm/migration.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 17
+sidebar_position: 18
 description: Database schema migrations
 ---
 

docs/orm/plugins/_category_.yml

@@ -1,4 +1,4 @@
-position: 13
+position: 14
 label: Plugins
 collapsible: true
 collapsed: true

docs/reference/zmodel/function.md

@@ -89,31 +89,31 @@ Functions related to input validation are documented in a [separate page](./inpu
 ### uuid()
 
 ```zmodel
-function uuid(): String {}
+function uuid(version: Int?, format: String?): String {}
 ```
 
 Generates a globally unique identifier based on the UUID spec.
 
 ### cuid()
 
 ```zmodel
-function cuid(version: Int?): String {}
+function cuid(version: Int?, format: String?): String {}
 ```
 
 Generates a unique identifier based on the [CUID](https://github.com/ericelliott/cuid) spec. Pass `2` as an argument to use [cuid2](https://github.com/paralleldrive/cuid2).
 
 ### nanoid()
 
 ```zmodel
-function nanoid(length: Int?): String {}
+function nanoid(length: Int?, format: String?): String {}
 ```
 
 Generates an identifier based on the [nanoid](https://github.com/ai/nanoid) spec.
 
 ### ulid()
 
 ```zmodel
-function ulid(): String {}
+function ulid(format: String?): String {}
 ```
 
 Generates a unique identifier based on the [ULID](https://github.com/ulid/spec) spec.