@object-ui/data-objectstack 17.1.0 → 17.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "17.1.0",
+  "version": "17.2.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,12 +22,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^17.0.0-rc.0",
-    "@object-ui/core": "17.1.0",
-    "@object-ui/types": "17.1.0"
+    "@objectstack/client": "^17.0.0-rc.1",
+    "@objectstack/spec": "^17.0.0-rc.1",
+    "@object-ui/core": "17.2.0",
+    "@object-ui/types": "17.2.0"
   },
   "devDependencies": {
-    "@objectstack/spec": "^17.0.0-rc.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"

package/src/cache/MetadataCache.ts

@@ -17,9 +17,18 @@ interface CachedSchema {
 }
 
 /**
- * Cache statistics for monitoring
+ * Statistics reported by {@link MetadataCache.getStats} for monitoring.
+ *
+ * NOT the spec's `CacheStats` (`@objectstack/spec/contracts`), whose name this
+ * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
+ * describes the platform's `ICacheService` — a server-side KV cache measured by
+ * `keyCount` and `memoryUsage`. This one describes the browser-side LRU in front
+ * of `/api/v1/meta/*`: it is bounded (`size`/`maxSize`), it evicts, it coalesces
+ * concurrent fetches onto one in-flight promise, and it reports a `hitRate`.
+ * Neither type has a key the other has, so this is a name collision, not a
+ * dialect — deriving would have replaced every field.
  */
-export interface CacheStats {
+export interface MetadataCacheStats {
   size: number;
   maxSize: number;
   hits: number;
@@ -218,7 +227,7 @@ export class MetadataCache {
    * 
    * @returns Cache statistics including hit rate
    */
-  getStats(): CacheStats {
+  getStats(): MetadataCacheStats {
     const total = this.stats.hits + this.stats.misses;
     const hitRate = total > 0 ? this.stats.hits / total : 0;
 

package/src/errors.test.ts

@@ -13,7 +13,7 @@ import {
   BulkOperationError,
   ConnectionError,
   AuthenticationError,
-  ValidationError,
+  DataApiValidationError,
   createErrorFromResponse,
   isObjectStackError,
   isErrorType,
@@ -189,20 +189,20 @@ describe('Error Classes', () => {
     });
   });
 
-  describe('ValidationError', () => {
+  describe('DataApiValidationError', () => {
     it('should create validation error', () => {
-      const error = new ValidationError('Invalid input');
+      const error = new DataApiValidationError('Invalid input');
 
       expect(error.message).toBe('Invalid input');
       expect(error.code).toBe('VALIDATION_ERROR');
       expect(error.statusCode).toBe(400);
       expect(error.name).toBe('ValidationError');
       expect(error).toBeInstanceOf(ObjectStackError);
-      expect(error).toBeInstanceOf(ValidationError);
+      expect(error).toBeInstanceOf(DataApiValidationError);
     });
 
     it('should include field information', () => {
-      const error = new ValidationError('Email is invalid', 'email');
+      const error = new DataApiValidationError('Email is invalid', 'email');
 
       expect(error.field).toBe('email');
       expect(error.details).toHaveProperty('field', 'email');
@@ -214,7 +214,7 @@ describe('Error Classes', () => {
         { field: 'age', message: 'Must be a positive number' },
       ];
       
-      const error = new ValidationError(
+      const error = new DataApiValidationError(
         'Validation failed',
         undefined,
         validationErrors
@@ -225,7 +225,7 @@ describe('Error Classes', () => {
     });
 
     it('should return empty array when no validation errors', () => {
-      const error = new ValidationError('Validation failed');
+      const error = new DataApiValidationError('Validation failed');
 
       expect(error.getValidationErrors()).toEqual([]);
     });
@@ -286,7 +286,7 @@ describe('Error Helpers', () => {
       expect(error.code).toBe('NOT_FOUND');
     });
 
-    it('should create ValidationError for 400 status', () => {
+    it('should create DataApiValidationError for 400 status', () => {
       const response = {
         status: 400,
         message: 'Bad request',
@@ -299,9 +299,9 @@ describe('Error Helpers', () => {
 
       const error = createErrorFromResponse(response);
 
-      expect(error).toBeInstanceOf(ValidationError);
+      expect(error).toBeInstanceOf(DataApiValidationError);
       expect(error.statusCode).toBe(400);
-      expect((error as ValidationError).validationErrors).toEqual([
+      expect((error as DataApiValidationError).validationErrors).toEqual([
         { field: 'email', message: 'Invalid email' },
       ]);
     });
@@ -379,7 +379,7 @@ describe('Error Helpers', () => {
       const bulkError = new BulkOperationError('create', 0, 1, []);
       const connError = new ConnectionError('timeout');
       const authError = new AuthenticationError();
-      const validError = new ValidationError('invalid');
+      const validError = new DataApiValidationError('invalid');
 
       expect(isObjectStackError(metadataError)).toBe(true);
       expect(isObjectStackError(bulkError)).toBe(true);
@@ -409,7 +409,7 @@ describe('Error Helpers', () => {
 
     it('should return false for non-matching error type', () => {
       const error = new MetadataNotFoundError('users');
-      expect(isErrorType(error, ValidationError)).toBe(false);
+      expect(isErrorType(error, DataApiValidationError)).toBe(false);
     });
 
     it('should return true for base class check', () => {

package/src/errors.ts

@@ -159,12 +159,24 @@ export class AuthenticationError extends ObjectStackError {
 }
 
 /**
- * Error thrown when data validation fails
+ * Error thrown when the ObjectStack data API rejects a write as invalid.
+ *
+ * NOT the spec's `ValidationError` (`@objectstack/spec/kernel`), whose name this
+ * class wore until objectui#3160 (objectstack#4115 ledger batch 6). That one is
+ * a plain DATA SHAPE — `{ field, message, code? }`, one entry in a plugin
+ * manifest's validation report — and `@object-ui/types` re-exports it under that
+ * name. This is a runtime `Error` subclass carrying an HTTP status plus a list
+ * of such entries, so the two are not even the same KIND of thing.
+ *
+ * The name follows the convention registered on objectstack#4115 for this
+ * family — `<what was validated>Validation<Error|Result>`. `@object-ui/core`
+ * took `SchemaNodeValidationError` for its SDUI-tree walk; this one belongs to
+ * the data API.
  */
-export class ValidationError extends ObjectStackError {
+export class DataApiValidationError extends ObjectStackError {
   /**
-   * Create a new ValidationError
-   * 
+   * Create a new DataApiValidationError
+   *
    * @param message - Human-readable error message
    * @param field - The field that failed validation (optional)
    * @param validationErrors - Array of validation error details
@@ -186,6 +198,12 @@ export class ValidationError extends ObjectStackError {
         ...details,
       }
     );
+    // The RUNTIME name stays `'ValidationError'` on purpose — it is the wire
+    // discriminator this adapter shares with `@objectstack/client` and with
+    // consumers that sniff `err.name` rather than `instanceof`
+    // (`normaliseClientError` here, `@object-ui/react`'s `error-message`).
+    // Renaming the TypeScript symbol is a source-level rename; renaming this
+    // string would be a behaviour change nobody asked for.
     this.name = 'ValidationError';
   }
 
@@ -232,7 +250,7 @@ export function createErrorFromResponse(response: Record<string, unknown>, conte
       return new ObjectStackError(message, 'NOT_FOUND', 404, details);
     
     case 400:
-      return new ValidationError(message, undefined, (response?.data as Record<string, unknown>)?.errors as Array<{ field: string; message: string }>, details);
+      return new DataApiValidationError(message, undefined, (response?.data as Record<string, unknown>)?.errors as Array<{ field: string; message: string }>, details);
     
     case 503:
       return new ConnectionError(message, (response?.config as Record<string, unknown>)?.url as string, details, 503);

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`
@@ -3511,14 +3517,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 +3552,7 @@ export type {
   MetadataClientConfig,
   MetadataListOptions,
   MetadataDraftHeader,
-  MetadataSaveOptions,
+  MetadataClientSaveOptions,
   MetadataGetOptions,
   MetadataDeleteOptions,
   MetadataHistoryOptions,
@@ -3563,7 +3569,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/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 };
   }
 }