@ultimat3/core 22.5.1 → 22.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "22.5.1",
+  "version": "22.6.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "22.5.1"
+    "@ultimat3/schema": "22.6.0"
   }
 }

package/src/client-paths.ts

@@ -51,12 +51,42 @@ export function pluralize(word: string): string {
   return `${word}s`;
 }
 
+/**
+ * How an action's export name becomes its URL. Declared once per app
+ * (`defineApi({ http: { pathStyle } })`), never per action — one app, one rule.
+ *
+ * | style | `publishPost` | `signIn` | `health` |
+ * |---|---|---|---|
+ * | `'resource'` (default) | `/api/posts/publish` | `/api/ins/sign` | `/api/healths/invoke` |
+ * | `'readable'` | `/api/publish-post` | `/api/sign-in` | `/api/health` |
+ *
+ * `'resource'` guesses a noun from the words after the first and pluralizes it, which is right for
+ * `verbNoun` names and ungrammatical for everything else. `'readable'` guesses nothing: the path IS
+ * the name, kebab-cased — the rule `/_x/query/<kebab>` has always followed for reads.
+ */
+export type ActionPathStyle = 'resource' | 'readable';
+
+export const ACTION_PATH_STYLES: readonly ActionPathStyle[] = ['resource', 'readable'];
+
+/** Every action is served under one prefix, whichever style derives the rest. */
+export const ACTION_PATH_PREFIX = '/api';
+
 /**
  * `publishPost` -> `/api/posts/publish`, `updateUserProfile` -> `/api/user-profiles/update`,
- * `checkout` -> `/api/checkouts/invoke` (single-word fallback).
+ * `checkout` -> `/api/checkouts/invoke` (single-word fallback) — the `'resource'` style.
+ * `'readable'` -> `/api/publish-post`, `/api/update-user-profile`, `/api/checkout`: `verb` is the
+ * first word and `resource` the rest, both unpluralized, and neither is part of the path.
  */
-export function actionRoute(name: string): ActionRoute {
+export function actionRoute(name: string, style: ActionPathStyle = 'resource'): ActionRoute {
   const words = splitWords(name);
+  if (style === 'readable') {
+    const kebab = words.length === 0 ? 'invoke' : words.join('-');
+    return {
+      verb: words[0] ?? 'invoke',
+      resource: words.length < 2 ? kebab : words.slice(1).join('-'),
+      path: `${ACTION_PATH_PREFIX}/${kebab}`,
+    };
+  }
   const head = words[0] ?? 'invoke';
   if (words.length < 2) {
     const resource = pluralize(head);
@@ -68,9 +98,9 @@ export function actionRoute(name: string): ActionRoute {
   return { verb: head, resource, path: `/api/${resource}/${head}` };
 }
 
-/** The path an action is POSTed to — `actionRoute(name).path`. */
-export function actionPath(name: string): string {
-  return actionRoute(name).path;
+/** The path an action is POSTed to — `actionRoute(name, style).path`. */
+export function actionPath(name: string, style: ActionPathStyle = 'resource'): string {
+  return actionRoute(name, style).path;
 }
 
 /** `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. */

package/src/index.ts

@@ -68,8 +68,10 @@ export type {
   FlightPlan,
 } from './client-flight';
 export { createClientFlight, DEFAULT_CLIENT_RETRY, isTransientFailure } from './client-flight';
-export type { ActionRoute } from './client-paths';
+export type { ActionPathStyle, ActionRoute } from './client-paths';
 export {
+  ACTION_PATH_PREFIX,
+  ACTION_PATH_STYLES,
   actionPath,
   actionRoute,
   pluralize,

package/src/telemetry.ts

@@ -69,6 +69,12 @@ export interface Span {
   addEvent(name: string, attributes?: SpanAttributes): Span;
   recordError(error: unknown): Span;
   setStatus(code: SpanStatusCode, message?: string): Span;
+  /**
+   * Rename a span that learned what it is only after it started — an HTTP server span is opened
+   * before the router matches, and its name must be the route PATTERN (`GET /r/:token`), never the
+   * concrete URL, which carries capability tokens. A no-op once the span has ended.
+   */
+  updateName(name: string): Span;
   end(): void;
 }
 
@@ -194,7 +200,8 @@ function inboundParent(parent: SpanContext | undefined): SpanContext | undefined
   return parent === undefined || parent.spanId === '' ? undefined : parent;
 }
 
-export function startSpan(name: string, options?: StartSpanOptions): Span {
+export function startSpan(initialName: string, options?: StartSpanOptions): Span {
+  let name = initialName;
   // A live span is what gives an outbound typed call a trace to continue; see the module.
   installTraceHeaders();
   const parent = options?.parent ?? currentSpanContext();
@@ -219,7 +226,9 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
   let ended = false;
 
   const span: Span = {
-    name,
+    get name(): string {
+      return name;
+    },
     context,
     get ended(): boolean {
       return ended;
@@ -260,6 +269,10 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
       status = { code, message };
       return span;
     },
+    updateName(next) {
+      if (!ended) name = next;
+      return span;
+    },
     end(): void {
       if (ended) return;
       ended = true;