UUIDs & IDs

{prefix}_{26-char-base32-encoded-uuidv7}

usr_01h2xcejqtf2nbrexx3vqjhp41    (user)
org_01h455d8sc2shh7cysq5bn60y0    (organization)
proj_01h455d8sc2shh7cysq5bn60y1   (project)
mem_01h455d8sc2shh7cysq5bn60y2    (organization member)
inv_01h455d8sc2shh7cysq5bn60y3    (invitation)

import (
	"github.com/k0rdent/shared/utils/typeid"
)

userId := typeid.GenerateResourceId("usr")
projectId := typeid.GenerateResourceId("proj")

import { typeid } from '@k0rdent/shared/utils/typeid';

const userId = typeid('usr');
// → "usr_01h2xcejqtf2nbrexx3vqjhp41"

const projectId = typeid('proj');
// → "proj_01h455d8sc2shh7cysq5bn60y1"

CREATE TABLE atlas.clusters (
  id TEXT PRIMARY KEY DEFAULT generate_prefixed_id('cls'),
  -- ...
);

import { decode } from '@k0rdent/shared/utils/typeid';

const { prefix, uuid } = decode('usr_01h2xcejqtf2nbrexx3vqjhp41');
// prefix → "usr"
// uuid   → "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"  (UUIDv7)

req_{region}-{timestamp_hex}-{entropy_hex}

req_us1-018f4a2b3c4d-a1b2c3d4e5f6g7h8
req_eu1-018f4a2b3c4d-9f8e7d6c5b4a3928
req_ap1-018f4a2b3c4d-1234567890abcdef

const REGION = process.env.K0RDENT_REGION ?? 'local';

function generateRequestId(): string {
  const ts = Date.now().toString(16).padStart(12, '0');
  const bytes = new Uint8Array(8);
  crypto.getRandomValues(bytes);
  const entropy = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
  return `req_${REGION}-${ts}-${entropy}`;
}

app.use((req, res, next) => {
  req.requestId = req.headers['x-request-id'] ?? generateRequestId();
  res.setHeader('x-request-id', req.requestId);
  next();
});

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have access to this project.",
    "requestId": "req_us1-018f4a2b3c4d-a1b2c3d4e5f6g7h8"
  }
}

logger.info('Project created', {
  requestId: req.requestId,
  projectId: project.id,
  organizationId: org.id,
});

3-39 characters, lowercase letters and digits, hyphens between words
Must start with a letter, cannot end with a hyphen

acme-corp        (from "Acme Corp")
my-startup       (from "My Startup")
cloudnative-io   (from "CloudNative.io")

import {
  suggestOrgSlug,
  validateOrgSlug,
  findAvailableSlug,
  isReservedSlug,
} from '@k0rdent/shared/utils/org-slug';

// Generate a slug suggestion from an org name
suggestOrgSlug('Acme Corp');          // → "acme-corp"
suggestOrgSlug('123 Industries');     // → "x123-industries" (prefixed — must start with letter)
suggestOrgSlug('New Corp');           // → "new-corp-a7f3" (reserved word gets random suffix)

// Validate a user-entered slug
validateOrgSlug('acme-corp');         // → { valid: true }
validateOrgSlug('ab');                // → { valid: false, error: 'TOO_SHORT' }
validateOrgSlug('admin');             // → { valid: false, error: 'RESERVED' }

// Find an available slug (checks DB)
const slug = await findAvailableSlug('acme-corp', async (s) => {
  const exists = await db.query('SELECT 1 FROM auth.organizations WHERE slug = $1', [s]);
  return exists.rowCount > 0;
});
// → "acme-corp" if available, otherwise "acme-corp-1", "acme-corp-2", etc.

k0r_{type}_{random_base62}

// In a service/handler
import { typeid } from '@k0rdent/shared/utils/typeid';

async function createCluster(input: CreateClusterInput) {
  const id = typeid('cls');

  await db.query(
    `INSERT INTO atlas.clusters (id, project_id, name, ...) VALUES ($1, $2, $3, ...)`,
    [id, input.projectId, input.name],
  );

  return { id, ...input };
}

function isValidTypedId(id: string, expectedPrefix: string): boolean {
  const parts = id.split('_');
  if (parts.length !== 2) return false;
  if (parts[0] !== expectedPrefix) return false;
  if (parts[1].length !== 26) return false;
  return /^[0-7][0-9a-hjkmnp-tv-z]{25}$/.test(parts[1]);
}

// Usage in route handler
app.get('/projects/:id', (req, res) => {
  if (!isValidTypedId(req.params.id, 'proj')) {
    return res.status(400).json({ error: { code: 'INVALID_ID', message: 'Invalid project ID format' } });
  }
  // ...
});

// Good — prefix stays
await queue.publish('cluster.created', { clusterId: 'cls_01h2xce...' });

// Bad — stripping the prefix defeats the purpose
await queue.publish('cluster.created', { clusterId: '01h2xce...' });

function createLogger(requestId: string) {
  return {
    info: (msg: string, meta?: Record<string, unknown>) =>
      console.log(JSON.stringify({ level: 'info', requestId, msg, ...meta, ts: new Date().toISOString() })),
    error: (msg: string, meta?: Record<string, unknown>) =>
      console.error(JSON.stringify({ level: 'error', requestId, msg, ...meta, ts: new Date().toISOString() })),
  };
}

// In a handler
const log = createLogger(req.requestId);
log.info('Deleting cluster', { clusterId: cluster.id, orgId: org.id });