doc: formatting IDs

[sanny-io]

zenstackhq/zenstack-v3#509

Summary by CodeRabbit

• New Features

  • Introduced ID formatting support for ZModel, allowing custom string formatting of generated IDs.

• Documentation

  • Updated ID function references to reflect new optional formatting parameter capabilities.
  • Reorganized ORM documentation structure for improved navigation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

@sanny-io is attempting to deploy a commit to the ZenStack Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Walkthrough

This PR updates documentation across multiple ORM guides and function references. It increments sidebar position metadata in several existing docs, introduces a new page documenting ID formatting functionality, and updates function signatures for ID generation functions (uuid, cuid, nanoid, ulid) to reflect optional format parameters.

Changes

Cohort / File(s)	Summary
Documentation Sidebar Metadata Updates docs/orm/benchmark.md, docs/orm/errors.md, docs/orm/inferred-types.md, docs/orm/logging.md, docs/orm/migration.md	Updated sidebar_position values incrementally across 5 files (offsets ranging from 14→15 to 18→19) to adjust navigation ordering
New ID Formatting Documentation docs/orm/formatting-ids.md	Introduces new documentation page describing ID formatting feature with format parameter support, usage examples, and error handling notes for format strings
Function Signature Reference Updates docs/reference/zmodel/function.md	Updated predefined ID function signatures to include optional format parameter: uuid() → uuid(version: Int?, format: String?), cuid(version: Int?) → cuid(version: Int?, format: String?), nanoid(length: Int?) → nanoid(length: Int?, format: String?), ulid() → ulid(format: String?)

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• docs: add missing nanoid function doc #368: Updates nanoid function signature documentation; this PR extends that change with the additional format parameter.
• doc: v2.11.1 release #421: Modifies ID function signatures in documentation; this PR continues related signature updates for ID functions (cuid, ulid, uuid, nanoid).

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'doc: formatting IDs' directly reflects the main change: documentation introducing a new ID formatting feature for ZModel, which is the primary focus of docs/orm/formatting-ids.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5405e06 and 92c5603.

⛔ Files ignored due to path filters (1)

• docs/orm/plugins/_category_.yml is excluded by !**/*.yml

📒 Files selected for processing (7)

• docs/orm/benchmark.md
• docs/orm/errors.md
• docs/orm/formatting-ids.md
• docs/orm/inferred-types.md
• docs/orm/logging.md
• docs/orm/migration.md
• docs/reference/zmodel/function.md

🧰 Additional context used

🪛 LanguageTool

docs/reference/zmodel/function.md

[grammar] ~113-~113: Ensure spelling is correct
Context: ...ttps://github.com/ai/nanoid) spec. ### ulid() ```zmodel function ulid(format: Stri...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (9)

docs/orm/benchmark.md (1)

2-2: Sidebar position update is consistent with cascading reorganization.

The change from 18 to 19 aligns with the insertion of the new formatting-ids.md at position 13, correctly shifting all downstream items.

docs/orm/logging.md (1)

2-2: Sidebar position updated consistently.

The position change from 14 to 15 reflects the cascading reorganization as expected.

docs/orm/inferred-types.md (1)

2-2: Sidebar position updated consistently.

The position change from 15 to 16 is correct and maintains the cascading shift.

docs/orm/migration.md (1)

2-2: Sidebar position updated consistently.

The position change from 17 to 18 follows the cascading shift pattern.

docs/orm/errors.md (1)

2-2: Sidebar position updated consistently.

The position change from 16 to 17 maintains the cascading shift for the sidebar reorganization.

docs/orm/formatting-ids.md (2)

1-30: Well-structured documentation for new ID formatting feature.

The file is clearly organized with proper front matter, component imports, and comprehensive explanations. The example code is accurate and the disclaimers about function signature variations are helpful.

---

19-19: Verify anchor link resolves to the function reference section.

The link references #predefined-functions which should resolve to the "## Predefined functions" heading in function.md. This will be verified when reviewing the corresponding file.

docs/reference/zmodel/function.md (2)

92-92: Function signatures correctly updated with format parameter.

All four ID generator functions now include an optional format parameter:

• uuid(version: Int?, format: String?) and cuid(version: Int?, format: String?) maintain their version parameters
• nanoid(length: Int?, format: String?) maintains its length parameter
• ulid(format: String?) adds format as its only parameter

These signatures align with the documentation in formatting-ids.md and the example code shown there (uuid(7, 'user_%s')). The variance in signatures is appropriately noted in the formatting-ids.md info box.

Also applies to: 100-100, 108-108, 116-116

---

83-119: Verify the "Predefined functions" section heading is correctly anchored.

The formatting-ids.md file (line 19) links to #predefined-functions which should resolve to the "## Predefined functions" heading at line 83. This appears correct based on standard Markdown anchor generation, but please verify the link works in the built documentation.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}