@danxbot/ui 3.7.0 → 3.8.0

package/dist/types/lib/records/wire.d.ts

@@ -0,0 +1,96 @@
+import type { RecordPayload } from "./types";
+/** A relation, once normalized: a pointer to another record's key. */
+export interface RecordRef {
+    readonly __ref: string;
+}
+export declare function isRecordRef(value: unknown): value is RecordRef;
+/**
+ * Strip a trailing `Resource` so a delete and the record it deletes land on
+ * the same key.
+ *
+ * CREATED AND DELETED PAYLOADS DISAGREE ABOUT `__type`, verified in the
+ * backend twice: created/updated take it from a resource class name that no
+ * resource overrides, so it keeps the suffix (`"WorkflowRunResource"`), while
+ * deletes take it from a helper that strips the suffix (`"WorkflowRun"`).
+ *
+ * A store keyed on the raw string files a delete under a different key than
+ * the record it is deleting, so the tombstone never lands and the row stays on
+ * screen forever. One line, and without it a whole class of update silently
+ * does nothing.
+ */
+export declare function normalizeTypeName(raw: string): string;
+/**
+ * `Type:id`, with the id COERCED TO A STRING.
+ *
+ * Ids are not uniformly numeric — a file's id is a UUID while a run's is an
+ * integer — and a Map keyed on the raw value would file `7` and `"7"`
+ * separately. There is deliberately NO `id || name` fallback: that is a quirk
+ * of one prior implementation, not part of any contract, and a record keyed on
+ * a name silently merges two different rows the day two of them share one.
+ */
+export declare function recordKey(type: string, id: string | number): string;
+/** The identity a payload carries, or `undefined` if it is not a record. */
+export interface PayloadIdentity {
+    readonly key: string;
+    readonly type: string;
+    readonly id: string;
+}
+export declare function payloadIdentity(payload: RecordPayload): PayloadIdentity | undefined;
+/**
+ * A `{__stale:true, id, __model}` ping: an invalidation the backend sends
+ * under the normal event name with NO `__type` at all.
+ *
+ * Recognised by name and dropped, because keying it would need a type it does
+ * not have — and guessing one from `__model` (a PHP class name) is exactly the
+ * sort of inference that produces a store full of records nothing reads.
+ */
+export declare function isStalePing(payload: RecordPayload): boolean;
+/**
+ * The tombstone marker, or `undefined`.
+ *
+ * BOTH SPELLINGS, deliberately. A `deleted` event carries `deleted_at`; a
+ * soft-delete arriving as an `updated` event carries `__deleted_at`. The prior
+ * art in this codebase checks only the second, so its delete handling has never
+ * run once — the payload says `deleted_at` and the store asks for
+ * `__deleted_at`.
+ */
+export declare function tombstoneAt(payload: RecordPayload): string | undefined;
+/**
+ * True when the payload says, in so many words, that the record is NOT
+ * deleted — which is what un-deletes a tombstoned record.
+ *
+ * Needed because absent keeps the previous value: without this, a record that
+ * was tombstoned could never come back, even when the server says it has.
+ */
+export declare function explicitlyUndeleted(payload: RecordPayload): boolean;
+/**
+ * Normalize `__timestamp` to milliseconds.
+ *
+ * IT ARRIVES IN TWO UNITS, 1000x APART, and this is verified rather than
+ * theoretical: the backend reads the model's `updated_at` in MILLISECONDS when
+ * the model has that column, and falls back to a SECONDS-resolution wall clock
+ * when it does not. At least one real model has no `updated_at` column at all.
+ *
+ * A comparison across the two units is not merely wrong, it is CONSISTENTLY
+ * wrong in one direction: a seconds value is ~1000x smaller, so it always
+ * loses to a milliseconds value and such a record would never update again.
+ *
+ * An implausible magnitude — below either window — is a contract violation,
+ * and it is surfaced rather than coerced. It returns `undefined`, which means
+ * "cannot adjudicate": the write is still ACCEPTED (a bogus tiny number must
+ * not be allowed to make a record permanently un-writable), it just cannot
+ * refuse anything.
+ */
+export declare function normalizeTimestamp(raw: unknown): number | undefined;
+/**
+ * Keys the store INTERPRETS rather than stores.
+ *
+ * Everything `__`-prefixed is envelope by this wire format's own convention,
+ * and two of them would actively break the store if kept as data:
+ * `__broadcasted_at` moves on every delivery, so storing it would make an
+ * identical redelivered payload look like a change and re-render the world —
+ * which is the exact cost the notify-only-if-changed rule exists to avoid.
+ *
+ * `deleted_at` is here because it is the tombstone marker, not a field.
+ */
+export declare function isEnvelopeKey(key: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",