@object-ui/data-objectstack 17.1.0 → 17.3.0

package/src/index.ts

@@ -7,6 +7,7 @@
  */
 
 import { ObjectStackClient, type QueryOptions as ObjectStackQueryOptions } from '@objectstack/client';
+import type { DroppedFieldsEvent } from '@objectstack/spec/data';
 import type {
   DataSource,
   BatchTransactionOperation,
@@ -39,7 +40,7 @@ import {
   MetadataNotFoundError,
   BulkOperationError,
   ConnectionError,
-  ValidationError,
+  DataApiValidationError,
   createErrorFromResponse,
 } from './errors';
 
@@ -588,7 +589,7 @@ export function isConcurrentUpdateError(error: unknown): error is ConcurrentUpda
  *
  * Two shapes are recognised:
  *   - `409` + `CONCURRENT_UPDATE` → {@link ConcurrentUpdateError};
- *   - `400` + `VALIDATION_FAILED` → {@link ValidationError}, carrying the
+ *   - `400` + `VALIDATION_FAILED` → {@link DataApiValidationError}, carrying the
  *     server's per-field entries so a form can mark the offending inputs
  *     instead of showing one undirected toast.
  */
@@ -621,7 +622,7 @@ export function normaliseClientError(error: unknown): unknown {
       })
       .filter((x): x is { field: string; message: string } => x !== null);
 
-    return new ValidationError(
+    return new DataApiValidationError(
       typeof e.message === 'string' ? e.message : 'Validation failed',
       validationErrors[0]?.field,
       validationErrors,
@@ -721,16 +722,21 @@ export type BatchProgressListener = (event: BatchProgressEvent) => void;
 /**
  * One server-reported write-strip: caller-supplied fields the backend LEGALLY
  * removed from a write before persisting (a non-system caller cannot seed a
- * `readonly` field, a `readonlyWhen` predicate locked it, etc.). Mirrors the
- * framework `DroppedFieldsEvent` (spec `DroppedFieldsEventSchema`) structurally
- * so we don't pin a client type version — `reason` is kept as a widened string
- * for forward-compatibility with reasons added server-side.
+ * `readonly` field, a `readonlyWhen` predicate locked it, etc.).
+ *
+ * THE spec type, re-exported (objectui#3160, objectstack#4115 ledger batch 6).
+ * Until then this was a hand copy whose comment said it "mirrors the framework
+ * `DroppedFieldsEvent` (spec `DroppedFieldsEventSchema`) structurally so we
+ * don't pin a client type version", with `reason` widened from the spec's
+ * `'readonly' | 'readonly_when'` to bare `string` "for forward-compatibility
+ * with reasons added server-side". Both halves of that reasoning are the
+ * failure mode this ledger exists to remove: the spec IS the client type
+ * version, and a consumer-side widening of a producer's enum is precisely the
+ * lenient fallback AGENTS.md #12 bans — it deletes the only compile-time signal
+ * that would tell `AdapterProvider`'s toast wording (which branches on
+ * `readonly_when`) that a new reason had appeared.
  */
-export interface DroppedFieldsEvent {
-  object: string;
-  fields: string[];
-  reason: string;
-}
+export type { DroppedFieldsEvent };
 
 /**
  * Emitted after a create/update whose response carried `droppedFields`
@@ -765,9 +771,68 @@ function stableStringify(value: unknown): string {
   return `{${keys.map(k => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
 }
 
+/**
+ * Whether two values are the SAME as far as the wire is concerned — used to
+ * tell a write-strip that lost something from one that lost nothing
+ * (objectui#3484).
+ *
+ * Deliberately strict: `1` and `'1'` are NOT the same here. A false "these are
+ * equal" silently swallows a warning about a value the user really did lose,
+ * which is the worse of the two errors; a false "these differ" only warns
+ * about a no-op. `null` and `undefined` both mean "empty" and do match.
+ */
+function sameWireValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  const aEmpty = a === null || a === undefined;
+  const bEmpty = b === null || b === undefined;
+  if (aEmpty || bEmpty) return aEmpty && bEmpty;
+  return stableStringify(a) === stableStringify(b);
+}
+
+/**
+ * Drop the fields whose strip changed nothing — the caller supplied exactly
+ * the value the record already holds (objectui#3484).
+ *
+ * The server is not wrong to report those: the client DID send the key and the
+ * engine DID refuse to write it, so `droppedFields` is an accurate account of
+ * the request. But "was not saved" is only news when something was actually
+ * lost, and the console's edit form used to round-trip the whole record —
+ * including fields it had itself rendered as read-only text — so every save of
+ * a state-locked record raised a warning listing fields the user never touched
+ * and whose values never changed.
+ *
+ * A field is kept (still warned about) whenever the no-op cannot be PROVEN:
+ * the response echoed no record, or that record does not carry the key.
+ *
+ * Returns entries with empty `fields` removed; an all-no-op event list comes
+ * back empty, which suppresses the warning entirely.
+ */
+function withoutNoOpDrops(
+  droppedFields: DroppedFieldsEvent[],
+  sent: Record<string, unknown> | undefined | null,
+  stored: Record<string, unknown> | undefined | null,
+): DroppedFieldsEvent[] {
+  if (!sent || !stored || typeof sent !== 'object' || typeof stored !== 'object') {
+    return droppedFields;
+  }
+  const out: DroppedFieldsEvent[] = [];
+  for (const e of droppedFields) {
+    const kept = e.fields.filter((f) => {
+      if (!Object.prototype.hasOwnProperty.call(sent, f)) return true;
+      if (!Object.prototype.hasOwnProperty.call(stored, f)) return true;
+      return !sameWireValue(
+        (sent as Record<string, unknown>)[f],
+        (stored as Record<string, unknown>)[f],
+      );
+    });
+    if (kept.length > 0) out.push({ ...e, fields: kept });
+  }
+  return out;
+}
+
 /**
  * ObjectStack Data Source Adapter
- * 
+ *
  * Bridges the ObjectStack Client SDK with the ObjectUI DataSource interface.
  * This allows Object UI applications to seamlessly integrate with ObjectStack
  * backends while maintaining the universal DataSource abstraction.
@@ -1303,13 +1368,17 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     resource: string,
     result: unknown,
     id?: string | number,
+    sent?: Record<string, unknown> | null,
   ): void {
     const dropped = (result as { droppedFields?: unknown } | null | undefined)?.droppedFields;
     if (!Array.isArray(dropped) || dropped.length === 0) return;
-    const droppedFields = dropped.filter(
+    const valid = dropped.filter(
       (e): e is DroppedFieldsEvent =>
         !!e && typeof e === 'object' && Array.isArray((e as DroppedFieldsEvent).fields) && (e as DroppedFieldsEvent).fields.length > 0,
     );
+    // A strip that changed nothing is not news — see withoutNoOpDrops (#3484).
+    const stored = (result as { record?: Record<string, unknown> } | null | undefined)?.record;
+    const droppedFields = withoutNoOpDrops(valid, sent, stored);
     if (droppedFields.length === 0) return;
     this.emitWriteWarning({ operation, resource, ...(id !== undefined ? { id } : {}), droppedFields });
   }
@@ -1332,11 +1401,25 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   ): void {
     const dropped = (payload as { droppedFields?: unknown } | null | undefined)?.droppedFields;
     if (!Array.isArray(dropped) || dropped.length === 0) return;
+    const results = (payload as { results?: unknown[] } | null | undefined)?.results;
     for (const entry of dropped) {
       if (!entry || typeof entry !== 'object') continue;
       const e = entry as DroppedFieldsEvent & { index?: number };
       if (!Array.isArray(e.fields) || e.fields.length === 0) continue;
       const op = typeof e.index === 'number' ? operations[e.index] : undefined;
+      // Same no-op suppression as the single-record path (#3484). The echoed
+      // row for the originating op is the "stored" side; when the batch echoed
+      // nothing usable, `withoutNoOpDrops` keeps every field.
+      const stored =
+        typeof e.index === 'number' && Array.isArray(results)
+          ? (results[e.index] as Record<string, unknown> | undefined)
+          : undefined;
+      const [live] = withoutNoOpDrops(
+        [{ object: e.object, fields: e.fields, reason: e.reason }],
+        op?.data as Record<string, unknown> | undefined,
+        stored,
+      );
+      if (!live) continue;
       // `delete` never drops fields; anything unexpected reads as an update,
       // which is the truthful default for a batch that echoed a strip.
       const operation: 'create' | 'update' = (op?.action ?? 'create') === 'create' ? 'create' : 'update';
@@ -1344,7 +1427,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         operation,
         resource: e.object ?? op?.object ?? '',
         ...(op?.id !== undefined && op?.id !== null ? { id: op.id } : {}),
-        droppedFields: [{ object: e.object, fields: e.fields, reason: e.reason }],
+        droppedFields: [live],
       });
     }
   }
@@ -1366,7 +1449,13 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     try {
       const result = await this.client.data.create<T>(resource, data);
       this.emitMutation({ type: 'create', resource, record: { ...result.record } });
-      this.notifyDroppedFields('create', resource, result, (result.record as { id?: string | number } | undefined)?.id);
+      this.notifyDroppedFields(
+        'create',
+        resource,
+        result,
+        (result.record as { id?: string | number } | undefined)?.id,
+        data as Record<string, unknown>,
+      );
       return result.record;
     } catch (err) {
       // `update` has always normalised; `create` did not, so a rejected insert
@@ -1403,7 +1492,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
       );
       this.emitMutation({ type: 'update', resource, id, record: { ...result.record } });
-      this.notifyDroppedFields('update', resource, result, id);
+      this.notifyDroppedFields('update', resource, result, id, data as Record<string, unknown>);
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -3511,14 +3600,14 @@ export {
   BulkOperationError,
   ConnectionError,
   AuthenticationError,
-  ValidationError,
+  DataApiValidationError,
   createErrorFromResponse,
   isObjectStackError,
   isErrorType,
 } from './errors';
 
 // Export cache types
-export type { CacheStats } from './cache/MetadataCache';
+export type { MetadataCacheStats } from './cache/MetadataCache';
 
 // v3.0.0 Deep Integration modules
 export { CloudOperations } from './cloud';
@@ -3546,7 +3635,7 @@ export type {
   MetadataClientConfig,
   MetadataListOptions,
   MetadataDraftHeader,
-  MetadataSaveOptions,
+  MetadataClientSaveOptions,
   MetadataGetOptions,
   MetadataDeleteOptions,
   MetadataHistoryOptions,
@@ -3563,7 +3652,7 @@ export type {
 } from './metadata-client';
 
 export { SecurityManager } from './security';
-export type { SecurityPolicy, CSPConfig, AuditLogConfig, AuditEventType, DataMaskingConfig, DataMaskingRule, AuditLogEntry } from './security';
+export type { SecurityManagerPolicy, CSPConfig, AuditLogConfig, AuditEventType, DataMaskingConfig, DataMaskingRule, AuditLogEntry } from './security';
 
 export { createDefaultCanvasConfig, snapToGrid, calculateAutoLayout } from './studio';
 export type { StudioCanvasConfig, StudioPropertyEditor, StudioThemeBuilderConfig, StudioColorPalette, StudioTypographyPreset, StudioShadowPreset } from './studio';

package/src/metadata-client.ts

@@ -75,7 +75,21 @@ export interface MetadataDraftHeader {
   updatedBy: string | null;
 }
 
-export interface MetadataSaveOptions {
+/**
+ * Options for {@link MetadataClient.save} — a WRITE OVER HTTP to
+ * `/api/v1/meta/:type/:name`.
+ *
+ * NOT the spec's `MetadataSaveOptions` (`@objectstack/spec/system` and
+ * `/kernel`), whose name this interface wore until objectui#3160
+ * (objectstack#4115 ledger batch 6). Both spec copies describe writing a
+ * metadata item to a FILE — `format: json|yaml|ts`, `path`, `indent`,
+ * `prettify`, `sortKeys`, `backup`, `atomic`, `loader`. Not one of those keys
+ * exists here, and not one of these exists there: this is the REST client's
+ * request envelope — optimistic concurrency (`ifMatch` → `If-Match`), actor
+ * attribution, the destructive-change override, the ADR-0033 draft/publish
+ * mode, and the owning package. Same words, different layer.
+ */
+export interface MetadataClientSaveOptions {
   /**
    * Optimistic concurrency token (the `checksum` returned by the last
    * read). When present, sent as the `If-Match` header so concurrent
@@ -122,7 +136,7 @@ export interface MetadataGetOptions {
   packageId?: string;
 }
 
-export interface MetadataDeleteOptions extends MetadataSaveOptions {
+export interface MetadataDeleteOptions extends MetadataClientSaveOptions {
   /**
    * Target state. `'draft'` discards the pending draft (keeps the
    * published overlay intact). Omit to reset the active overlay back
@@ -527,7 +541,7 @@ export class MetadataClient {
     type: string,
     name: string,
     item: unknown,
-    options: MetadataSaveOptions = {},
+    options: MetadataClientSaveOptions = {},
   ): Promise<T> {
     if (!name || !String(name).trim()) {
       // The `PUT /meta/:type/:name` route rejects a missing `:name` segment

package/src/onWriteWarning.test.ts

@@ -157,6 +157,107 @@ describe('ObjectStackAdapter.onWriteWarning', () => {
     expect(events).toHaveLength(1);
   });
 
+  // ── no-op strips are not news (objectui#3484) ─────────────────────────────
+  //
+  // The server is right to report a strip — the client DID send the key. But
+  // "was not saved" is only worth a toast when something was LOST. The console
+  // edit form used to round-trip the whole record, so every save of a
+  // state-locked record warned about fields the user never touched whose values
+  // never changed. When the echoed record proves the stripped value equals what
+  // was sent, stay quiet.
+
+  it('suppresses the warning when every stripped value equals what the record already holds', async () => {
+    const update = vi.fn().mockResolvedValue({
+      record: { id: 'r1', type: 'quality_abnormal', source_method: 'qc_judgment', title: 'B' },
+      droppedFields: [
+        { object: 'andon', fields: ['type', 'source_method'], reason: 'readonly_when' },
+      ],
+    });
+    const ds = makeDS({ update });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.update('andon', 'r1', {
+      title: 'B',
+      type: 'quality_abnormal',
+      source_method: 'qc_judgment',
+    });
+
+    expect(events).toEqual([]);
+  });
+
+  it('still warns about the fields that really did change, and only those', async () => {
+    const update = vi.fn().mockResolvedValue({
+      record: { id: 'r1', type: 'quality_abnormal', source_method: 'qc_judgment' },
+      droppedFields: [
+        { object: 'andon', fields: ['type', 'source_method'], reason: 'readonly_when' },
+      ],
+    });
+    const ds = makeDS({ update });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    // The user really did try to change `type`; `source_method` round-tripped.
+    await ds.update('andon', 'r1', { type: 'equipment_fault', source_method: 'qc_judgment' });
+
+    expect(events).toEqual([
+      {
+        operation: 'update',
+        resource: 'andon',
+        id: 'r1',
+        droppedFields: [{ object: 'andon', fields: ['type'], reason: 'readonly_when' }],
+      },
+    ]);
+  });
+
+  it('keeps the warning when the no-op cannot be PROVEN (record echo lacks the key)', async () => {
+    const update = vi.fn().mockResolvedValue({
+      record: { id: 'r1' },
+      droppedFields: [{ object: 'andon', fields: ['type'], reason: 'readonly_when' }],
+    });
+    const ds = makeDS({ update });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.update('andon', 'r1', { type: 'quality_abnormal' });
+
+    expect(events).toHaveLength(1);
+  });
+
+  it('does not treat a type change as a no-op (1 is not "1")', async () => {
+    const update = vi.fn().mockResolvedValue({
+      record: { id: 'r1', tax_rate: '9' },
+      droppedFields: [{ object: 'invoice', fields: ['tax_rate'], reason: 'readonly_when' }],
+    });
+    const ds = makeDS({ update });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.update('invoice', 'r1', { tax_rate: 9 });
+
+    expect(events).toHaveLength(1);
+  });
+
+  it('suppresses a no-op strip on the cross-object batch path too', async () => {
+    const batchTransaction = vi.fn().mockResolvedValue({
+      results: [{ id: 'acc1' }, { id: 'inv1', tax_rate: 9 }],
+      droppedFields: [
+        { object: 'invoice', fields: ['tax_rate'], reason: 'readonly_when', index: 1 },
+      ],
+    });
+    const ds = makeDS({ batchTransaction });
+    ds.atomicBatchCapability = true;
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.batchTransaction([
+      { object: 'account', action: 'create', data: { name: 'Acme' } },
+      { object: 'invoice', action: 'update', id: 'inv1', data: { status: 'paid', tax_rate: 9 } },
+    ]);
+
+    expect(events).toEqual([]);
+  });
+
   it('isolates a throwing listener so the write still resolves and other listeners fire', async () => {
     const update = vi.fn().mockResolvedValue({ record: { id: 'r1' }, droppedFields: ONE_DROP });
     const ds = makeDS({ update });

package/src/security.ts

@@ -11,7 +11,20 @@
  * Provides advanced security policies: CSP config, audit logging, data masking.
  */
 
-export interface SecurityPolicy {
+/**
+ * Configuration for {@link SecurityManager} — this adapter's browser-side
+ * security posture: the CSP header it generates, the in-memory audit log it
+ * keeps, and the field-masking rules it applies before a record is rendered.
+ *
+ * NOT the spec's `SecurityPolicy` (`@objectstack/spec/kernel`), whose name this
+ * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
+ * is the PACKAGE SUPPLY-CHAIN policy — `{ id, name, autoScan, thresholds,
+ * allowedLicenses, prohibitedLicenses, codeSigning, sandbox }` — the rules a
+ * marketplace applies when scanning a plugin before install. It shares no key
+ * with this one, so there was nothing to derive; the collision is the word
+ * "security", not the concept.
+ */
+export interface SecurityManagerPolicy {
   /** Content Security Policy configuration */
   csp?: CSPConfig;
   /** Audit logging configuration */
@@ -100,10 +113,10 @@ export interface AuditLogEntry {
  * Handles CSP generation, audit logging, and data masking.
  */
 export class SecurityManager {
-  private policy: SecurityPolicy;
+  private policy: SecurityManagerPolicy;
   private auditLog: AuditLogEntry[] = [];
 
-  constructor(policy: SecurityPolicy = {}) {
+  constructor(policy: SecurityManagerPolicy = {}) {
     this.policy = policy;
   }
 
@@ -204,14 +217,14 @@ export class SecurityManager {
   /**
    * Update the security policy.
    */
-  updatePolicy(policy: Partial<SecurityPolicy>): void {
+  updatePolicy(policy: Partial<SecurityManagerPolicy>): void {
     this.policy = { ...this.policy, ...policy };
   }
 
   /**
    * Get current security policy.
    */
-  getPolicy(): SecurityPolicy {
+  getPolicy(): SecurityManagerPolicy {
     return { ...this.policy };
   }
 }