@revisium/schema-toolkit 0.5.0 → 0.9.0

package/README.md

@@ -4,181 +4,59 @@
 
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=revisium_schema-toolkit&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=revisium_schema-toolkit)
 [![codecov](https://codecov.io/gh/revisium/schema-toolkit/graph/badge.svg?token=OLFXI79CN3)](https://codecov.io/gh/revisium/schema-toolkit)
-[![GitHub License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/revisium/prisma-pg-json/blob/master/LICENSE)
+[![GitHub License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/revisium/schema-toolkit/blob/master/LICENSE)
 [![GitHub Release](https://img.shields.io/github/v/release/revisium/schema-toolkit)](https://github.com/revisium/schema-toolkit/releases)
 
-**Universal TypeScript toolkit for JSON Schema definitions used across the Revisium ecosystem.**
+Framework-agnostic TypeScript types, system schemas, runtime stores, and utilities for working with JSON Schema in [Revisium](https://revisium.io) projects.
 
 </div>
 
-## Overview
-
-`@revisium/schema-toolkit` provides framework-agnostic TypeScript types, system schemas, runtime stores, utilities, and testing helpers for working with JSON Schema in Revisium projects. This package contains shared code used by `revisium-core`, `revisium-endpoint`, and `revisium-admin`.
-
-## Features
-
-- 🎯 **TypeScript Types** - Complete type definitions for JSON Schema, JSON Patch, JSON Value Patch, and migrations
-- 🔧 **System Schemas** - Pre-defined schemas for Revisium system fields (row ID, timestamps, file handling, etc.)
-- 🏪 **Runtime Stores** - Schema and value store classes for runtime manipulation
-- 🛠️ **Utilities** - 18+ utility functions for schema operations, patches, foreign keys, and more
-- 🧪 **Test Utilities** - Helper functions for generating mock schemas in tests
-- ✅ **Validation Schemas** - Ajv-compatible validation schemas (optional)
-- 🌐 **Framework Agnostic** - No dependencies on backend/frontend frameworks (only `nanoid` for ID generation)
-- 📦 **Tree-shakeable** - Use only what you need with ES modules
-
 ## Installation
 
 ```bash
 npm install @revisium/schema-toolkit
 ```
 
-## Usage
+## API
 
-### TypeScript Types
+### Schema
 
-```typescript
-import {
-  JsonSchema,
-  JsonObjectSchema,
-  JsonSchemaTypeName,
-} from '@revisium/schema-toolkit/types';
+| Function | Description |
+|----------|-------------|
+| `createJsonSchemaStore` | Create runtime schema store |
+| `getJsonSchemaStoreByPath` | Navigate schema by path |
+| `applyPatches` | Apply JSON Patch operations to schema |
+| `resolveRefs` | Resolve $ref to inline schemas |
+| `validateJsonFieldName` | Validate field name format |
+| `getInvalidFieldNamesInSchema` | Find invalid field names in schema |
 
-const userSchema: JsonObjectSchema = {
-  type: JsonSchemaTypeName.Object,
-  properties: {
-    name: { type: JsonSchemaTypeName.String, default: '' },
-    age: { type: JsonSchemaTypeName.Number, default: 0 },
-  },
-};
-```
+### Value
 
-### System Schemas
-
-```typescript
-import {
-  rowIdSchema,
-  rowCreatedAtSchema,
-  fileSchema,
-} from '@revisium/schema-toolkit/plugins';
-```
-
-### Model Stores
-
-```typescript
-import {
-  createJsonSchemaStore,
-  createJsonValueStore,
-} from '@revisium/schema-toolkit/lib';
-
-// Create schema store
-const schemaStore = createJsonSchemaStore({
-  type: 'object',
-  properties: {
-    name: { type: 'string', default: '' },
-  },
-});
-
-// Create value store
-const valueStore = createJsonValueStore(
-  schemaStore,
-  'row-id-123',
-  { name: 'John' }
-);
-```
+| Function | Description |
+|----------|-------------|
+| `createJsonValueStore` | Create runtime value store |
+| `getJsonValueByPath` | Navigate value by path |
+| `computeValueDiff` | Compute field-level diff between two values |
+| `traverseValue` | Traverse value tree |
 
-### Utilities
+### Foreign Keys
 
-```typescript
-import {
-  applyPatches,
-  getForeignKeysFromSchema,
-  resolveRefs,
-} from '@revisium/schema-toolkit/lib';
-
-// Apply JSON patches to schema
-const updatedSchema = applyPatches(schema, patches);
-
-// Get foreign keys from schema
-const foreignKeys = getForeignKeysFromSchema(schemaStore);
-
-// Resolve $ref in schemas (endpoint feature)
-const resolved = resolveRefs(schemaWithRefs);
-```
-
-### Test Utilities
-
-```typescript
-import {
-  getStringSchema,
-  getObjectSchema,
-  getRefSchema,
-} from '@revisium/schema-toolkit/mocks';
-
-const mockSchema = getObjectSchema({
-  name: getStringSchema(),
-  userId: getStringSchema({ foreignKey: 'User' }),
-  avatar: getRefSchema('File'),
-});
-```
+| Function | Description |
+|----------|-------------|
+| `getForeignKeysFromSchema` | Extract foreign keys from schema |
+| `getForeignKeysFromValue` | Extract foreign key values from data |
+| `getForeignKeyPatchesFromSchema` | Get patches for foreign key changes |
+| `replaceForeignKeyValue` | Replace foreign key references |
 
-## API Reference
+### Path Utils
 
-### Entry Points
-
-- `@revisium/schema-toolkit` - All exports (convenience)
-- `@revisium/schema-toolkit/types` - TypeScript types only
-- `@revisium/schema-toolkit/plugins` - System schemas
-- `@revisium/schema-toolkit/mocks` - Test utilities
-- `@revisium/schema-toolkit/consts` - Constants (CustomSchemeKeywords, SystemSchemaIds)
-- `@revisium/schema-toolkit/model` - Schema and value stores
-- `@revisium/schema-toolkit/lib` - Utility functions
-- `@revisium/schema-toolkit/validation-schemas` - Ajv validation schemas
-
-### Key Utilities
-
-**Schema Operations:**
-- `createJsonSchemaStore(schema)` - Create runtime schema store
-- `getJsonSchemaStoreByPath(store, path)` - Navigate schema by JSON pointer
-- `applyPatches(schema, patches)` - Apply JSON Patch operations
-
-**Value Operations:**
-- `createJsonValueStore(schema, rowId, data)` - Create runtime value store
-- `getJsonValueStoreByPath(store, path)` - Navigate value by JSON pointer
-
-**Foreign Keys:**
-- `getForeignKeysFromSchema(store)` - Extract foreign keys from schema
-- `getForeignKeysFromValue(store)` - Extract foreign key values from data
-- `replaceForeignKeyValue(store, fromId, toId)` - Replace foreign key references
-
-**Other:**
-- `resolveRefs(schema)` - Resolve $ref to inline schemas
-- `validateJsonFieldName(name)` - Validate field name format
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Run tests with coverage
-npm run test:cov
-
-# Lint
-npm run lint:ci
-
-# Format
-npm run format
-
-# Type check
-npm run tsc
-```
+| Function | Description |
+|----------|-------------|
+| `parsePath` | Parse dot-notation path to segments |
+| `getParentForPath` | Get parent path |
+| `getPathByStore` | Get path from store |
+| `deepEqual` | Deep equality comparison |
 
 ## License
 
-MIT
+MIT

package/dist/{chunk-7LKKRGZG.js → chunk-DFL3HJ4Y.js}

@@ -248,129 +248,6 @@ var applyMovePatch = (store, patch) => {
   throw new Error('Invalid type of "to" parent');
 };
 
-// src/lib/getDBJsonPathByJsonSchemaStore.ts
-var getDBJsonPathByJsonSchemaStore = (store) => {
-  let node = store;
-  let path = "";
-  while (node.parent) {
-    if (node.parent.type === "object" /* Object */) {
-      path = `.${node.name}${path}`;
-    } else if (node.parent.type === "array" /* Array */) {
-      path = `[*]${path}`;
-    }
-    node = node.parent;
-  }
-  if (!path) {
-    return "$";
-  }
-  return `$${path}`;
-};
-
-// src/lib/getPathByStore.ts
-var getPathByStore = (store) => {
-  let node = store;
-  let path = "";
-  while (node.parent) {
-    if (node.parent.type === "object" /* Object */) {
-      path = `/properties/${node.name}${path}`;
-    } else if (node.parent.type === "array" /* Array */) {
-      path = `/items${path}`;
-    }
-    node = node.parent;
-  }
-  if (!path) {
-    return "/";
-  }
-  return `${path}`;
-};
-
-// src/lib/traverseStore.ts
-var traverseStore = (store, callback) => {
-  callback(store);
-  if (store.type === "object" /* Object */) {
-    Object.values(store.properties).forEach((item) => {
-      traverseStore(item, callback);
-    });
-  } else if (store.type === "array" /* Array */) {
-    traverseStore(store.items, callback);
-  }
-};
-
-// src/lib/getForeignKeyPatchesFromSchema.ts
-var getForeignKeyPatchesFromSchema = (store, options) => {
-  const stores = [];
-  traverseStore(store, (item) => {
-    if (item.type === "string" /* String */ && item.foreignKey === options.tableId) {
-      item.foreignKey = options.nextTableId;
-      const patch = {
-        op: "replace",
-        path: getPathByStore(item),
-        value: item.getPlainSchema()
-      };
-      stores.push(patch);
-    }
-  });
-  return stores;
-};
-
-// src/lib/getForeignKeysFromSchema.ts
-var getForeignKeysFromSchema = (store) => {
-  const foreignKeys = /* @__PURE__ */ new Set();
-  traverseStore(store, (item) => {
-    if (item.type === "string" /* String */ && item.foreignKey) {
-      foreignKeys.add(item.foreignKey);
-    }
-  });
-  return [...foreignKeys].sort((a, b) => a.localeCompare(b));
-};
-
-// src/lib/traverseValue.ts
-var traverseValue = (store, callback) => {
-  callback(store);
-  if (store.type === "object" /* Object */) {
-    Object.values(store.value).forEach((item) => {
-      traverseValue(item, callback);
-    });
-  } else if (store.type === "array" /* Array */) {
-    store.value.forEach((itemValue) => {
-      traverseValue(itemValue, callback);
-    });
-  }
-};
-
-// src/lib/getForeignKeysFromValue.ts
-var getForeignKeysFromValue = (value) => {
-  const foreignKeys = /* @__PURE__ */ new Map();
-  traverseValue(value, (item) => {
-    if (item.type === "string" /* String */ && item.foreignKey) {
-      let tableForeignKey = foreignKeys.get(item.foreignKey);
-      if (!tableForeignKey) {
-        tableForeignKey = /* @__PURE__ */ new Set();
-        foreignKeys.set(item.foreignKey, tableForeignKey);
-      }
-      tableForeignKey.add(item.getPlainValue());
-    }
-  });
-  return [...foreignKeys].map(([tableId, rowIds]) => ({
-    tableId,
-    rowIds: [...rowIds].sort((a, b) => a.localeCompare(b))
-  }));
-};
-
-// src/lib/getInvalidFieldNamesInSchema.ts
-var getInvalidFieldNamesInSchema = (schema, refs = {}) => {
-  const schemaStore = createJsonSchemaStore(schema, refs);
-  const invalidFields = [];
-  traverseStore(schemaStore, (item) => {
-    if (item.parent?.type === "object" /* Object */) {
-      if (!validateJsonFieldName(item.name)) {
-        invalidFields.push(item);
-      }
-    }
-  });
-  return invalidFields;
-};
-
 // src/lib/json-path-utils.ts
 function parsePathSegments(path) {
   const segments = [];
@@ -595,6 +472,221 @@ function convertSchemaPathToJsonPath(schemaPath) {
   return result;
 }
 
+// src/lib/computeValueDiff.ts
+function computeValueDiff(fromValue, toValue) {
+  if (fromValue === null && toValue === null) {
+    return [];
+  }
+  if (fromValue === null && toValue !== null) {
+    return [createChange("", null, toValue, "ADDED" /* Added */)];
+  }
+  if (fromValue !== null && toValue === null) {
+    return [createChange("", fromValue, null, "REMOVED" /* Removed */)];
+  }
+  return computeDiff(fromValue, toValue, "");
+}
+function computeDiff(fromValue, toValue, path) {
+  if (deepEqual(fromValue, toValue)) {
+    return [];
+  }
+  if (isPrimitive(fromValue) || isPrimitive(toValue)) {
+    return [createChange(path, fromValue, toValue, "MODIFIED" /* Modified */)];
+  }
+  if (hasTypeChanged(fromValue, toValue)) {
+    return [createChange(path, fromValue, toValue, "MODIFIED" /* Modified */)];
+  }
+  if (Array.isArray(fromValue) && Array.isArray(toValue)) {
+    return computeArrayDiff(fromValue, toValue, path);
+  }
+  return computeObjectDiff(
+    fromValue,
+    toValue,
+    path
+  );
+}
+function computeObjectDiff(fromObj, toObj, basePath) {
+  const changes = [];
+  const fromKeys = Object.keys(fromObj);
+  const toKeys = new Set(Object.keys(toObj));
+  for (const key of fromKeys) {
+    const fieldPath = joinPath(basePath, key);
+    if (!toKeys.has(key)) {
+      changes.push(
+        createChange(fieldPath, fromObj[key], null, "REMOVED" /* Removed */)
+      );
+    } else {
+      changes.push(...computeDiff(fromObj[key], toObj[key], fieldPath));
+    }
+  }
+  for (const key of toKeys) {
+    if (!fromKeys.includes(key)) {
+      const fieldPath = joinPath(basePath, key);
+      changes.push(
+        createChange(fieldPath, null, toObj[key], "ADDED" /* Added */)
+      );
+    }
+  }
+  return changes;
+}
+function computeArrayDiff(fromArr, toArr, basePath) {
+  const changes = [];
+  const maxLen = Math.max(fromArr.length, toArr.length);
+  for (let i = 0; i < maxLen; i++) {
+    const fieldPath = joinPath(basePath, String(i));
+    const hasFrom = i < fromArr.length;
+    const hasTo = i < toArr.length;
+    if (hasFrom && hasTo) {
+      changes.push(...computeDiff(fromArr[i], toArr[i], fieldPath));
+    } else if (hasFrom) {
+      changes.push(
+        createChange(fieldPath, fromArr[i], null, "REMOVED" /* Removed */)
+      );
+    } else {
+      changes.push(
+        createChange(fieldPath, null, toArr[i], "ADDED" /* Added */)
+      );
+    }
+  }
+  return changes;
+}
+function isPrimitive(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function hasTypeChanged(fromValue, toValue) {
+  const fromIsArray = Array.isArray(fromValue);
+  const toIsArray = Array.isArray(toValue);
+  return fromIsArray !== toIsArray;
+}
+function joinPath(base, segment) {
+  return base ? `${base}.${segment}` : segment;
+}
+function createChange(path, oldValue, newValue, changeType) {
+  return { path, oldValue, newValue, changeType };
+}
+
+// src/lib/getDBJsonPathByJsonSchemaStore.ts
+var getDBJsonPathByJsonSchemaStore = (store) => {
+  let node = store;
+  let path = "";
+  while (node.parent) {
+    if (node.parent.type === "object" /* Object */) {
+      path = `.${node.name}${path}`;
+    } else if (node.parent.type === "array" /* Array */) {
+      path = `[*]${path}`;
+    }
+    node = node.parent;
+  }
+  if (!path) {
+    return "$";
+  }
+  return `$${path}`;
+};
+
+// src/lib/getPathByStore.ts
+var getPathByStore = (store) => {
+  let node = store;
+  let path = "";
+  while (node.parent) {
+    if (node.parent.type === "object" /* Object */) {
+      path = `/properties/${node.name}${path}`;
+    } else if (node.parent.type === "array" /* Array */) {
+      path = `/items${path}`;
+    }
+    node = node.parent;
+  }
+  if (!path) {
+    return "/";
+  }
+  return `${path}`;
+};
+
+// src/lib/traverseStore.ts
+var traverseStore = (store, callback) => {
+  callback(store);
+  if (store.type === "object" /* Object */) {
+    Object.values(store.properties).forEach((item) => {
+      traverseStore(item, callback);
+    });
+  } else if (store.type === "array" /* Array */) {
+    traverseStore(store.items, callback);
+  }
+};
+
+// src/lib/getForeignKeyPatchesFromSchema.ts
+var getForeignKeyPatchesFromSchema = (store, options) => {
+  const stores = [];
+  traverseStore(store, (item) => {
+    if (item.type === "string" /* String */ && item.foreignKey === options.tableId) {
+      item.foreignKey = options.nextTableId;
+      const patch = {
+        op: "replace",
+        path: getPathByStore(item),
+        value: item.getPlainSchema()
+      };
+      stores.push(patch);
+    }
+  });
+  return stores;
+};
+
+// src/lib/getForeignKeysFromSchema.ts
+var getForeignKeysFromSchema = (store) => {
+  const foreignKeys = /* @__PURE__ */ new Set();
+  traverseStore(store, (item) => {
+    if (item.type === "string" /* String */ && item.foreignKey) {
+      foreignKeys.add(item.foreignKey);
+    }
+  });
+  return [...foreignKeys].sort((a, b) => a.localeCompare(b));
+};
+
+// src/lib/traverseValue.ts
+var traverseValue = (store, callback) => {
+  callback(store);
+  if (store.type === "object" /* Object */) {
+    Object.values(store.value).forEach((item) => {
+      traverseValue(item, callback);
+    });
+  } else if (store.type === "array" /* Array */) {
+    store.value.forEach((itemValue) => {
+      traverseValue(itemValue, callback);
+    });
+  }
+};
+
+// src/lib/getForeignKeysFromValue.ts
+var getForeignKeysFromValue = (value) => {
+  const foreignKeys = /* @__PURE__ */ new Map();
+  traverseValue(value, (item) => {
+    if (item.type === "string" /* String */ && item.foreignKey) {
+      let tableForeignKey = foreignKeys.get(item.foreignKey);
+      if (!tableForeignKey) {
+        tableForeignKey = /* @__PURE__ */ new Set();
+        foreignKeys.set(item.foreignKey, tableForeignKey);
+      }
+      tableForeignKey.add(item.getPlainValue());
+    }
+  });
+  return [...foreignKeys].map(([tableId, rowIds]) => ({
+    tableId,
+    rowIds: [...rowIds].sort((a, b) => a.localeCompare(b))
+  }));
+};
+
+// src/lib/getInvalidFieldNamesInSchema.ts
+var getInvalidFieldNamesInSchema = (schema, refs = {}) => {
+  const schemaStore = createJsonSchemaStore(schema, refs);
+  const invalidFields = [];
+  traverseStore(schemaStore, (item) => {
+    if (item.parent?.type === "object" /* Object */) {
+      if (!validateJsonFieldName(item.name)) {
+        invalidFields.push(item);
+      }
+    }
+  });
+  return invalidFields;
+};
+
 // src/lib/getJsonValueByPath.ts
 var getJsonValueStoreByPath = (root, path) => {
   if (!path) {
@@ -725,6 +817,6 @@ var SchemaTable = class {
   }
 };
 
-export { SchemaTable, VALIDATE_JSON_FIELD_NAME_ERROR_MESSAGE, applyAddPatch, applyMovePatch, applyRemovePatch, applyReplacePatch, convertJsonPathToSchemaPath, convertSchemaPathToJsonPath, createJsonObjectSchemaStore, createJsonSchemaStore, createPrimitiveStoreBySchema, deepEqual, getDBJsonPathByJsonSchemaStore, getForeignKeyPatchesFromSchema, getForeignKeysFromSchema, getForeignKeysFromValue, getInvalidFieldNamesInSchema, getJsonSchemaStoreByPath, getJsonValueStoreByPath, getParentForPath, getPathByStore, getValueByPath, hasPath, parsePath, pluginRefs, replaceForeignKeyValue, resolveRefs, saveSharedFields, setValueByPath, traverseStore, traverseValue, validateJsonFieldName };
-//# sourceMappingURL=chunk-7LKKRGZG.js.map
-//# sourceMappingURL=chunk-7LKKRGZG.js.map
+export { SchemaTable, VALIDATE_JSON_FIELD_NAME_ERROR_MESSAGE, applyAddPatch, applyMovePatch, applyRemovePatch, applyReplacePatch, computeValueDiff, convertJsonPathToSchemaPath, convertSchemaPathToJsonPath, createJsonObjectSchemaStore, createJsonSchemaStore, createPrimitiveStoreBySchema, deepEqual, getDBJsonPathByJsonSchemaStore, getForeignKeyPatchesFromSchema, getForeignKeysFromSchema, getForeignKeysFromValue, getInvalidFieldNamesInSchema, getJsonSchemaStoreByPath, getJsonValueStoreByPath, getParentForPath, getPathByStore, getValueByPath, hasPath, parsePath, pluginRefs, replaceForeignKeyValue, resolveRefs, saveSharedFields, setValueByPath, traverseStore, traverseValue, validateJsonFieldName };
+//# sourceMappingURL=chunk-DFL3HJ4Y.js.map
+//# sourceMappingURL=chunk-DFL3HJ4Y.js.map