From 92c56031ee6d4abd5f2d0a0e35920bba7ba35163 Mon Sep 17 00:00:00 2001 From: sanny-io Date: Thu, 25 Dec 2025 08:42:17 +0000 Subject: [PATCH] doc: formatting IDs --- docs/orm/benchmark.md | 2 +- docs/orm/errors.md | 2 +- docs/orm/formatting-ids.md | 30 ++++++++++++++++++++++++++++++ docs/orm/inferred-types.md | 2 +- docs/orm/logging.md | 2 +- docs/orm/migration.md | 2 +- docs/orm/plugins/_category_.yml | 2 +- docs/reference/zmodel/function.md | 8 ++++---- 8 files changed, 40 insertions(+), 10 deletions(-) create mode 100644 docs/orm/formatting-ids.md diff --git a/docs/orm/benchmark.md b/docs/orm/benchmark.md index 2e6850dd..3df6af2c 100644 --- a/docs/orm/benchmark.md +++ b/docs/orm/benchmark.md @@ -1,5 +1,5 @@ --- -sidebar_position: 18 +sidebar_position: 19 description: ORM performance benchmark --- diff --git a/docs/orm/errors.md b/docs/orm/errors.md index b71a239a..bf5ff03b 100644 --- a/docs/orm/errors.md +++ b/docs/orm/errors.md @@ -1,5 +1,5 @@ --- -sidebar_position: 16 +sidebar_position: 17 description: ORM Errors --- diff --git a/docs/orm/formatting-ids.md b/docs/orm/formatting-ids.md new file mode 100644 index 00000000..1329b73d --- /dev/null +++ b/docs/orm/formatting-ids.md @@ -0,0 +1,30 @@ +--- +sidebar_position: 13 +description: Formatting IDs in ZModel +--- + +import ZenStackVsPrisma from '../_components/ZenStackVsPrisma'; + +# Formatting IDs + + +ID formatting is a ZModel feature and doesn't exist in Prisma. + + +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. \ No newline at end of file diff --git a/docs/orm/inferred-types.md b/docs/orm/inferred-types.md index a34e7521..89a56d15 100644 --- a/docs/orm/inferred-types.md +++ b/docs/orm/inferred-types.md @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 16 description: TypeScript types derived from the ZModel schema --- diff --git a/docs/orm/logging.md b/docs/orm/logging.md index 357ecad4..8a2f61ca 100644 --- a/docs/orm/logging.md +++ b/docs/orm/logging.md @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 15 description: Setup logging --- diff --git a/docs/orm/migration.md b/docs/orm/migration.md index 42e2c614..de352809 100644 --- a/docs/orm/migration.md +++ b/docs/orm/migration.md @@ -1,5 +1,5 @@ --- -sidebar_position: 17 +sidebar_position: 18 description: Database schema migrations --- diff --git a/docs/orm/plugins/_category_.yml b/docs/orm/plugins/_category_.yml index 5effe808..1b2dbe73 100644 --- a/docs/orm/plugins/_category_.yml +++ b/docs/orm/plugins/_category_.yml @@ -1,4 +1,4 @@ -position: 13 +position: 14 label: Plugins collapsible: true collapsed: true diff --git a/docs/reference/zmodel/function.md b/docs/reference/zmodel/function.md index 66c0bfa1..e441ed31 100644 --- a/docs/reference/zmodel/function.md +++ b/docs/reference/zmodel/function.md @@ -89,7 +89,7 @@ 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. @@ -97,7 +97,7 @@ 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). @@ -105,7 +105,7 @@ Generates a unique identifier based on the [CUID](https://github.com/ericelliott ### 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. @@ -113,7 +113,7 @@ 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.