@object-ui/core 3.4.0 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @object-ui/core
 
+## 4.0.1
+
+### Patch Changes
+
+- @object-ui/types@4.0.1
+
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @object-ui/types@4.0.0
+
 ## 3.4.0
 
 ### Patch Changes

package/README.md

@@ -58,6 +58,41 @@ const userName = scope.get('user.name') // 'John'
 const isAdmin = scope.evaluate('${user.role === "admin"}') // true
 ```
 
+### System Views (`defineView`)
+
+Schemas authored in source code are part of the product contract and must
+not be mutated at runtime. Wrap them with `defineView()` to deep-freeze the
+graph and tag it as a *System View*.
+
+```typescript
+import { defineView, cloneAsOverride, isSystemView } from '@object-ui/core'
+
+export const userListView = defineView({
+  type: 'list',
+  data: { object: 'User' },
+  columns: [{ name: 'email' }],
+})
+
+userListView.columns.push({ name: 'name' }) // ❌ TypeError (strict mode)
+isSystemView(userListView)                   // ✅ true
+
+// To produce a Tenant- or User-level override, derive a mutable copy:
+const draft = cloneAsOverride(userListView)
+draft.columns.push({ name: 'name' })         // ✅ allowed
+isSystemView(draft)                          // false — clone is no longer System
+```
+
+**View tiers (recommended layering):**
+
+| Tier        | Source                | Mutable? | API                         |
+| ----------- | --------------------- | -------- | --------------------------- |
+| System View | code (`import` / `as const`) | ❌ frozen | `defineView()`              |
+| Tenant View | backend / DB          | ⚠️ admin only | `cloneAsOverride()` + persist |
+| User View   | localStorage / API    | ✅ user-editable | `cloneAsOverride()` + persist |
+
+`Date`, `RegExp`, `Map`, `Set`, and class instances passed via `props` are
+intentionally **not** frozen so infrastructure objects keep working.
+
 ## Philosophy
 
 This package is designed to be **framework-agnostic**. It contains:

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from './errors/index.js';
 export * from './utils/debug.js';
 export * from './utils/debug-collector.js';
 export * from './utils/merge-views-into-objects.js';
+export * from './utils/freeze-schema.js';
 export * from './protocols/index.js';
 /**
  * @deprecated Import `composeStacks` from `@objectstack/spec` instead.

package/dist/index.js

@@ -25,6 +25,7 @@ export * from './errors/index.js';
 export * from './utils/debug.js';
 export * from './utils/debug-collector.js';
 export * from './utils/merge-views-into-objects.js';
+export * from './utils/freeze-schema.js';
 export * from './protocols/index.js';
 /**
  * @deprecated Import `composeStacks` from `@objectstack/spec` instead.

package/dist/utils/freeze-schema.d.ts

@@ -0,0 +1,86 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * System View immutability layer.
+ *
+ * A "System View" is any UI schema authored in source code (imported `.ts`/`.json`,
+ * `as const` literals, or returned from a `defineView()` call). Such schemas are
+ * part of the product contract and MUST NOT be mutated at runtime. Mutation
+ * would cause behavior drift, break TypeScript inference, and bypass code review.
+ *
+ * Tenant- and user-level overrides should produce a *new* object via
+ * `cloneAsOverride()` rather than mutating the source schema.
+ *
+ * Design notes:
+ *   - Uses `Object.freeze` recursively (shallow-frozen objects can still be
+ *     mutated through nested references, which would defeat the purpose).
+ *   - Skips `Date`, `RegExp`, `Map`, `Set`, and class instances to avoid
+ *     freezing infrastructure objects users may pass through `props`.
+ *   - Tags the root with a non-enumerable Symbol so the renderer / DevTools
+ *     can detect the origin without polluting JSON serialization.
+ */
+/**
+ * Symbol marker stamped on every System View root. Non-enumerable so it
+ * never appears in `JSON.stringify`, `Object.keys`, or `{...spread}`.
+ */
+export declare const SYSTEM_VIEW_MARKER: unique symbol;
+/**
+ * Recursively type values as `readonly`. Equivalent to TS' built-in
+ * `Readonly<T>` but applied at every depth.
+ */
+export type DeepReadonly<T> = T extends (...args: any[]) => any ? T : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * A schema that has been frozen by `defineView()`. The marker symbol is
+ * non-enumerable and therefore invisible to consumers, but its presence
+ * lets us discriminate at runtime.
+ */
+export type SystemView<T> = DeepReadonly<T> & {
+    readonly [SYSTEM_VIEW_MARKER]?: true;
+};
+/**
+ * Recursively freeze an object graph. Cycles are tolerated via a `WeakSet`
+ * guard. Returns the same reference, narrowed to `DeepReadonly<T>`.
+ */
+export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): DeepReadonly<T>;
+/**
+ * Mark and freeze a code-loaded schema as a System View.
+ *
+ * @example
+ * ```ts
+ * import { defineView } from '@object-ui/core';
+ *
+ * export const userListView = defineView({
+ *   type: 'list',
+ *   data: { object: 'User' },
+ *   columns: [{ name: 'email' }],
+ * });
+ *
+ * // Type-checked AND runtime-checked: throws in strict mode, no-op silently otherwise.
+ * userListView.columns.push({ name: 'name' });
+ * ```
+ *
+ * To produce a mutable derivative (Tenant or User View), call
+ * `cloneAsOverride(userListView)`.
+ */
+export declare function defineView<T extends object>(schema: T): SystemView<T>;
+/**
+ * Runtime check: was this object produced by `defineView()` (or loaded from a
+ * source that forwards the marker)?
+ */
+export declare function isSystemView(value: unknown): boolean;
+/**
+ * Produce a deep, mutable clone of a System View so callers can apply
+ * Tenant/User overrides without touching the source schema.
+ *
+ * Implementation note: uses `structuredClone` when available (Node 17+, all
+ * evergreen browsers) and falls back to a JSON round-trip. The marker
+ * symbol is intentionally NOT copied — the clone is no longer a System View.
+ */
+export declare function cloneAsOverride<T>(view: T): T;

package/dist/utils/freeze-schema.js

@@ -0,0 +1,146 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * System View immutability layer.
+ *
+ * A "System View" is any UI schema authored in source code (imported `.ts`/`.json`,
+ * `as const` literals, or returned from a `defineView()` call). Such schemas are
+ * part of the product contract and MUST NOT be mutated at runtime. Mutation
+ * would cause behavior drift, break TypeScript inference, and bypass code review.
+ *
+ * Tenant- and user-level overrides should produce a *new* object via
+ * `cloneAsOverride()` rather than mutating the source schema.
+ *
+ * Design notes:
+ *   - Uses `Object.freeze` recursively (shallow-frozen objects can still be
+ *     mutated through nested references, which would defeat the purpose).
+ *   - Skips `Date`, `RegExp`, `Map`, `Set`, and class instances to avoid
+ *     freezing infrastructure objects users may pass through `props`.
+ *   - Tags the root with a non-enumerable Symbol so the renderer / DevTools
+ *     can detect the origin without polluting JSON serialization.
+ */
+/**
+ * Symbol marker stamped on every System View root. Non-enumerable so it
+ * never appears in `JSON.stringify`, `Object.keys`, or `{...spread}`.
+ */
+export const SYSTEM_VIEW_MARKER = Symbol.for('@object-ui/core/system-view');
+/**
+ * Values that should NOT be frozen — they are infrastructure objects whose
+ * internal mutability is required for correct operation.
+ */
+function isFreezableObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Object.isFrozen(value))
+        return false;
+    // Built-in types whose internals must remain mutable.
+    if (value instanceof Date)
+        return false;
+    if (value instanceof RegExp)
+        return false;
+    if (value instanceof Map)
+        return false;
+    if (value instanceof Set)
+        return false;
+    if (value instanceof WeakMap)
+        return false;
+    if (value instanceof WeakSet)
+        return false;
+    if (value instanceof Promise)
+        return false;
+    if (typeof value.then === 'function')
+        return false;
+    // Skip class instances (anything not a plain object or array).
+    if (!Array.isArray(value)) {
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null)
+            return false;
+    }
+    return true;
+}
+/**
+ * Recursively freeze an object graph. Cycles are tolerated via a `WeakSet`
+ * guard. Returns the same reference, narrowed to `DeepReadonly<T>`.
+ */
+export function deepFreeze(value, seen = new WeakSet()) {
+    if (!isFreezableObject(value))
+        return value;
+    if (seen.has(value))
+        return value;
+    seen.add(value);
+    // Freeze children first so the root reflects a fully-frozen graph.
+    for (const key of Object.keys(value)) {
+        const child = value[key];
+        if (isFreezableObject(child)) {
+            deepFreeze(child, seen);
+        }
+    }
+    Object.freeze(value);
+    return value;
+}
+/**
+ * Mark and freeze a code-loaded schema as a System View.
+ *
+ * @example
+ * ```ts
+ * import { defineView } from '@object-ui/core';
+ *
+ * export const userListView = defineView({
+ *   type: 'list',
+ *   data: { object: 'User' },
+ *   columns: [{ name: 'email' }],
+ * });
+ *
+ * // Type-checked AND runtime-checked: throws in strict mode, no-op silently otherwise.
+ * userListView.columns.push({ name: 'name' });
+ * ```
+ *
+ * To produce a mutable derivative (Tenant or User View), call
+ * `cloneAsOverride(userListView)`.
+ */
+export function defineView(schema) {
+    if (schema == null || typeof schema !== 'object') {
+        throw new TypeError('[ObjectUI] defineView() expects a non-null object schema.');
+    }
+    // Stamp the marker on the root only — nested nodes share origin via lineage.
+    // Non-enumerable keeps it out of JSON, spreads, and Object.keys.
+    if (!Object.prototype.hasOwnProperty.call(schema, SYSTEM_VIEW_MARKER)) {
+        Object.defineProperty(schema, SYSTEM_VIEW_MARKER, {
+            value: true,
+            enumerable: false,
+            configurable: false,
+            writable: false,
+        });
+    }
+    return deepFreeze(schema);
+}
+/**
+ * Runtime check: was this object produced by `defineView()` (or loaded from a
+ * source that forwards the marker)?
+ */
+export function isSystemView(value) {
+    return (value != null &&
+        typeof value === 'object' &&
+        value[SYSTEM_VIEW_MARKER] === true);
+}
+/**
+ * Produce a deep, mutable clone of a System View so callers can apply
+ * Tenant/User overrides without touching the source schema.
+ *
+ * Implementation note: uses `structuredClone` when available (Node 17+, all
+ * evergreen browsers) and falls back to a JSON round-trip. The marker
+ * symbol is intentionally NOT copied — the clone is no longer a System View.
+ */
+export function cloneAsOverride(view) {
+    if (view == null || typeof view !== 'object')
+        return view;
+    const clone = typeof structuredClone === 'function'
+        ? structuredClone(view)
+        : JSON.parse(JSON.stringify(view));
+    return clone;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "3.4.0",
+  "version": "4.0.1",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -28,7 +28,7 @@
     "@objectstack/spec": "^4.0.4",
     "lodash": "^4.18.1",
     "zod": "^4.4.3",
-    "@object-ui/types": "3.4.0"
+    "@object-ui/types": "4.0.1"
   },
   "devDependencies": {
     "typescript": "^6.0.3",