@revisium/schema-toolkit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Kashirov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+<div align="center">
+
+# @revisium/schema-toolkit
+
+[![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 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.**
+
+</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
+
+### TypeScript Types
+
+```typescript
+import {
+  JsonSchema,
+  JsonObjectSchema,
+  JsonSchemaTypeName,
+} from '@revisium/schema-toolkit/types';
+
+const userSchema: JsonObjectSchema = {
+  type: JsonSchemaTypeName.Object,
+  properties: {
+    name: { type: JsonSchemaTypeName.String, default: '' },
+    age: { type: JsonSchemaTypeName.Number, default: 0 },
+  },
+};
+```
+
+### 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' }
+);
+```
+
+### Utilities
+
+```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'),
+});
+```
+
+## API Reference
+
+### 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
+```
+
+## License
+
+MIT

package/dist/consts/index.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+// src/consts/system-schema-ids.ts
+var SystemSchemaIds = /* @__PURE__ */ ((SystemSchemaIds2) => {
+  SystemSchemaIds2["RowId"] = "urn:jsonschema:io:revisium:row-id-schema:1.0.0";
+  SystemSchemaIds2["RowCreatedId"] = "urn:jsonschema:io:revisium:row-created-id-schema:1.0.0";
+  SystemSchemaIds2["RowVersionId"] = "urn:jsonschema:io:revisium:row-version-id-schema:1.0.0";
+  SystemSchemaIds2["RowCreatedAt"] = "urn:jsonschema:io:revisium:row-created-at-schema:1.0.0";
+  SystemSchemaIds2["RowPublishedAt"] = "urn:jsonschema:io:revisium:row-published-at-schema:1.0.0";
+  SystemSchemaIds2["RowUpdatedAt"] = "urn:jsonschema:io:revisium:row-updated-at-schema:1.0.0";
+  SystemSchemaIds2["RowHash"] = "urn:jsonschema:io:revisium:row-hash-schema:1.0.0";
+  SystemSchemaIds2["RowSchemaHash"] = "urn:jsonschema:io:revisium:row-schema-hash-schema:1.0.0";
+  SystemSchemaIds2["File"] = "urn:jsonschema:io:revisium:file-schema:1.0.0";
+  return SystemSchemaIds2;
+})(SystemSchemaIds || {});
+
+// src/consts/index.ts
+var CustomSchemeKeywords = /* @__PURE__ */ ((CustomSchemeKeywords2) => {
+  CustomSchemeKeywords2["ForeignKey"] = "foreignKey";
+  return CustomSchemeKeywords2;
+})(CustomSchemeKeywords || {});
+
+exports.CustomSchemeKeywords = CustomSchemeKeywords;
+exports.SystemSchemaIds = SystemSchemaIds;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/consts/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/consts/system-schema-ids.ts","../../src/consts/index.ts"],"names":["SystemSchemaIds","CustomSchemeKeywords"],"mappings":";;;AAAO,IAAK,eAAA,qBAAAA,gBAAAA,KAAL;AACL,EAAAA,iBAAA,OAAA,CAAA,GAAQ,gDAAA;AACR,EAAAA,iBAAA,cAAA,CAAA,GAAe,wDAAA;AACf,EAAAA,iBAAA,cAAA,CAAA,GAAe,wDAAA;AACf,EAAAA,iBAAA,cAAA,CAAA,GAAe,wDAAA;AACf,EAAAA,iBAAA,gBAAA,CAAA,GAAiB,0DAAA;AACjB,EAAAA,iBAAA,cAAA,CAAA,GAAe,wDAAA;AACf,EAAAA,iBAAA,SAAA,CAAA,GAAU,kDAAA;AACV,EAAAA,iBAAA,eAAA,CAAA,GAAgB,yDAAA;AAChB,EAAAA,iBAAA,MAAA,CAAA,GAAO,8CAAA;AATG,EAAA,OAAAA,gBAAAA;AAAA,CAAA,EAAA,eAAA,IAAA,EAAA;;;ACAL,IAAK,oBAAA,qBAAAC,qBAAAA,KAAL;AACL,EAAAA,sBAAA,YAAA,CAAA,GAAa,YAAA;AADH,EAAA,OAAAA,qBAAAA;AAAA,CAAA,EAAA,oBAAA,IAAA,EAAA","file":"index.cjs","sourcesContent":["export enum SystemSchemaIds {\n  RowId = 'urn:jsonschema:io:revisium:row-id-schema:1.0.0',\n  RowCreatedId = 'urn:jsonschema:io:revisium:row-created-id-schema:1.0.0',\n  RowVersionId = 'urn:jsonschema:io:revisium:row-version-id-schema:1.0.0',\n  RowCreatedAt = 'urn:jsonschema:io:revisium:row-created-at-schema:1.0.0',\n  RowPublishedAt = 'urn:jsonschema:io:revisium:row-published-at-schema:1.0.0',\n  RowUpdatedAt = 'urn:jsonschema:io:revisium:row-updated-at-schema:1.0.0',\n  RowHash = 'urn:jsonschema:io:revisium:row-hash-schema:1.0.0',\n  RowSchemaHash = 'urn:jsonschema:io:revisium:row-schema-hash-schema:1.0.0',\n  File = 'urn:jsonschema:io:revisium:file-schema:1.0.0',\n}\n","export enum CustomSchemeKeywords {\n  ForeignKey = 'foreignKey',\n}\n\nexport * from './system-schema-ids.js';\n"]}

package/dist/consts/index.d.cts

@@ -0,0 +1,17 @@
+declare enum SystemSchemaIds {
+    RowId = "urn:jsonschema:io:revisium:row-id-schema:1.0.0",
+    RowCreatedId = "urn:jsonschema:io:revisium:row-created-id-schema:1.0.0",
+    RowVersionId = "urn:jsonschema:io:revisium:row-version-id-schema:1.0.0",
+    RowCreatedAt = "urn:jsonschema:io:revisium:row-created-at-schema:1.0.0",
+    RowPublishedAt = "urn:jsonschema:io:revisium:row-published-at-schema:1.0.0",
+    RowUpdatedAt = "urn:jsonschema:io:revisium:row-updated-at-schema:1.0.0",
+    RowHash = "urn:jsonschema:io:revisium:row-hash-schema:1.0.0",
+    RowSchemaHash = "urn:jsonschema:io:revisium:row-schema-hash-schema:1.0.0",
+    File = "urn:jsonschema:io:revisium:file-schema:1.0.0"
+}
+
+declare enum CustomSchemeKeywords {
+    ForeignKey = "foreignKey"
+}
+
+export { CustomSchemeKeywords, SystemSchemaIds };

package/dist/consts/index.d.ts

@@ -0,0 +1,17 @@
+declare enum SystemSchemaIds {
+    RowId = "urn:jsonschema:io:revisium:row-id-schema:1.0.0",
+    RowCreatedId = "urn:jsonschema:io:revisium:row-created-id-schema:1.0.0",
+    RowVersionId = "urn:jsonschema:io:revisium:row-version-id-schema:1.0.0",
+    RowCreatedAt = "urn:jsonschema:io:revisium:row-created-at-schema:1.0.0",
+    RowPublishedAt = "urn:jsonschema:io:revisium:row-published-at-schema:1.0.0",
+    RowUpdatedAt = "urn:jsonschema:io:revisium:row-updated-at-schema:1.0.0",
+    RowHash = "urn:jsonschema:io:revisium:row-hash-schema:1.0.0",
+    RowSchemaHash = "urn:jsonschema:io:revisium:row-schema-hash-schema:1.0.0",
+    File = "urn:jsonschema:io:revisium:file-schema:1.0.0"
+}
+
+declare enum CustomSchemeKeywords {
+    ForeignKey = "foreignKey"
+}
+
+export { CustomSchemeKeywords, SystemSchemaIds };

package/dist/consts/index.js

@@ -0,0 +1,23 @@
+// src/consts/system-schema-ids.ts
+var SystemSchemaIds = /* @__PURE__ */ ((SystemSchemaIds2) => {
+  SystemSchemaIds2["RowId"] = "urn:jsonschema:io:revisium:row-id-schema:1.0.0";
+  SystemSchemaIds2["RowCreatedId"] = "urn:jsonschema:io:revisium:row-created-id-schema:1.0.0";
+  SystemSchemaIds2["RowVersionId"] = "urn:jsonschema:io:revisium:row-version-id-schema:1.0.0";
+  SystemSchemaIds2["RowCreatedAt"] = "urn:jsonschema:io:revisium:row-created-at-schema:1.0.0";
+  SystemSchemaIds2["RowPublishedAt"] = "urn:jsonschema:io:revisium:row-published-at-schema:1.0.0";
+  SystemSchemaIds2["RowUpdatedAt"] = "urn:jsonschema:io:revisium:row-updated-at-schema:1.0.0";
+  SystemSchemaIds2["RowHash"] = "urn:jsonschema:io:revisium:row-hash-schema:1.0.0";
+  SystemSchemaIds2["RowSchemaHash"] = "urn:jsonschema:io:revisium:row-schema-hash-schema:1.0.0";
+  SystemSchemaIds2["File"] = "urn:jsonschema:io:revisium:file-schema:1.0.0";
+  return SystemSchemaIds2;
+})(SystemSchemaIds || {});
+
+// src/consts/index.ts
+var CustomSchemeKeywords = /* @__PURE__ */ ((CustomSchemeKeywords2) => {
+  CustomSchemeKeywords2["ForeignKey"] = "foreignKey";
+  return CustomSchemeKeywords2;
+})(CustomSchemeKeywords || {});
+
+export { CustomSchemeKeywords, SystemSchemaIds };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/consts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/consts/system-schema-ids.ts","../../src/consts/index.ts"],"names":["SystemSchemaIds","CustomSchemeKeywords"],"mappings":";AAAO,IAAK,eAAA,qBAAAA,gBAAAA,KAAL;AACL,EAAAA,iBAAA,OAAA,CAAA,GAAQ,gDAAA;AACR,EAAAA,iBAAA,cAAA,CAAA,GAAe,wDAAA;AACf,EAAAA,iBAAA,cAAA,CAAA,GAAe,wDAAA;AACf,EAAAA,iBAAA,cAAA,CAAA,GAAe,wDAAA;AACf,EAAAA,iBAAA,gBAAA,CAAA,GAAiB,0DAAA;AACjB,EAAAA,iBAAA,cAAA,CAAA,GAAe,wDAAA;AACf,EAAAA,iBAAA,SAAA,CAAA,GAAU,kDAAA;AACV,EAAAA,iBAAA,eAAA,CAAA,GAAgB,yDAAA;AAChB,EAAAA,iBAAA,MAAA,CAAA,GAAO,8CAAA;AATG,EAAA,OAAAA,gBAAAA;AAAA,CAAA,EAAA,eAAA,IAAA,EAAA;;;ACAL,IAAK,oBAAA,qBAAAC,qBAAAA,KAAL;AACL,EAAAA,sBAAA,YAAA,CAAA,GAAa,YAAA;AADH,EAAA,OAAAA,qBAAAA;AAAA,CAAA,EAAA,oBAAA,IAAA,EAAA","file":"index.js","sourcesContent":["export enum SystemSchemaIds {\n  RowId = 'urn:jsonschema:io:revisium:row-id-schema:1.0.0',\n  RowCreatedId = 'urn:jsonschema:io:revisium:row-created-id-schema:1.0.0',\n  RowVersionId = 'urn:jsonschema:io:revisium:row-version-id-schema:1.0.0',\n  RowCreatedAt = 'urn:jsonschema:io:revisium:row-created-at-schema:1.0.0',\n  RowPublishedAt = 'urn:jsonschema:io:revisium:row-published-at-schema:1.0.0',\n  RowUpdatedAt = 'urn:jsonschema:io:revisium:row-updated-at-schema:1.0.0',\n  RowHash = 'urn:jsonschema:io:revisium:row-hash-schema:1.0.0',\n  RowSchemaHash = 'urn:jsonschema:io:revisium:row-schema-hash-schema:1.0.0',\n  File = 'urn:jsonschema:io:revisium:file-schema:1.0.0',\n}\n","export enum CustomSchemeKeywords {\n  ForeignKey = 'foreignKey',\n}\n\nexport * from './system-schema-ids.js';\n"]}