Aurex Plugin for ZenStack
npm install zenstack-aurex-pluginDeterministic, namespace-aware Aurex ID generation for ZenStack v3.
This plugin integrates Aurex as the default ID strategy for your
ZenStack models, generating compact, human-readable, checksum-protected
identifiers with embedded namespace support.
---
This plugin:
- Automatically injects Aurex IDs into all models
- Generates deterministic prefix mappings per model
- Produces a manifest file (prefix contract)
- Enforces collision-safe prefix inference
- Uses a single global variant (Aurex16 or Aurex24)
No per-model configuration is required.
---
``bash`
npm install zenstack-aurex-plugin
---
`prisma
plugin aurex {
provider = "zenstack-aurex-plugin"
variant = "A16" // A16 or A24 (default: A16)
output = "../src/generated"
updateManifest = false // Not implemented yet (v0.0.1)
}
`
---
Use the helper type:
`prisma`
model User with Aurex {
// Other fields
}
> type Aurex is a helper type that expands to a compatibleid String @id @db.VarChar(24) @default(dbgenerated("#placeholder#"))
> field.
---
Every model will automatically:
- Receive a deterministic prefix
- Be included in the manifest
- Use the configured global variant
You do not need @@aurex for basic usage.
---
You may override the inferred prefix:
`prisma
model User with Aurex {
// ...
@@aurex(prefix: "US")
}
`
@@aurex is optional.
If omitted, the prefix will be inferred using model name hashing.
---
The plugin generates a contract file:
`ts`
const manifest = {
"variant": "A16",
"models": [
{
idFields: ["id"];
name: "User";
prefix: "FA";
}
]
} as const;
export default manifest;
This file ensures:
- Stable prefix assignments
- Reproducible builds
- Explicit breaking changes (Not implemented yet (v0.0.1))
(Not implemented yet (v0.0.1)) If a prefix changes and updateManifest = false, generation fails.
To approve changes:
`prisma`
updateManifest = true // Not implemented yet (v0.0.1)
---
In your application:
`ts
import manifest from "../aurex-manifest.ts";
import { AurexPlugin } from "zenstack-aurex-plugin";
db.$use(new AurexPlugin(manifest));
`
The runtime plugin:
- Injects Aurex IDs during create
- (Not implemented yet) Optionally validates provided IDs
- (Not implemented yet) Ensures checksum correctness
---
Variant is global:
`prisma`
variant = "A16"
Available options:
- A16 → Aurex16 (65 bits entropy, Luhn checksum)A24` → Aurex24 (90 bits entropy, CRC-20 checksum)
-
Per-model variants are intentionally not supported.
---
- Compact identifiers
- Human-readable
- Embedded namespace
- Built-in checksum
- Deterministic prefix mapping
- Versioned prefix contract
- Safe schema evolution
---
The plugin fails generation if:
- Prefix collision detected
- (Not implemented yet (v0.0.1)) Manifest changes without approval
- Invalid variant is provided
- Invalid prefix override is declared
All failures are explicit and intentional.
---
Aurex is a structured alternative to UUID for systems where humans
interact with identifiers.
It provides:
- Smaller printable footprint
- Checksum validation
- Namespace awareness
- Deterministic formatting
---
MIT