diff --git a/packages/foundation/core/RUNTIME_INTEGRATION.md b/packages/foundation/core/RUNTIME_INTEGRATION.md new file mode 100644 index 00000000..a8471c3a --- /dev/null +++ b/packages/foundation/core/RUNTIME_INTEGRATION.md @@ -0,0 +1,121 @@ +# ObjectStack Runtime Integration + +This document explains the integration of `@objectstack/runtime` and `@objectstack/objectql` into the ObjectQL platform. + +## Overview + +As of version 3.0.1, ObjectQL core integrates with the latest ObjectStack runtime packages: + +- **@objectstack/spec@0.1.2**: Protocol specification with TypeScript interfaces +- **@objectstack/objectql@0.1.1**: Core ObjectQL engine with basic driver management +- **@objectstack/runtime@0.1.1**: Runtime kernel with application lifecycle orchestration + +## Architecture + +### Package Relationship + +``` +@objectql/core (this package) +├── Extends/complements @objectstack/objectql +├── Uses types from @objectstack/spec +└── Re-exports types from @objectstack/runtime +``` + +### Type Exports + +The core package exports types from the runtime packages for API compatibility: + +```typescript +// Type-only exports to avoid runtime issues +export type { + ObjectStackKernel, + ObjectStackRuntimeProtocol +} from '@objectstack/runtime'; + +export type { + ObjectQL as ObjectQLEngine, + SchemaRegistry +} from '@objectstack/objectql'; +``` + +## Implementation Details + +### Current ObjectQL vs. ObjectQLEngine + +The current `ObjectQL` class in this package is a **production-ready, feature-rich** implementation that includes: + +- Full metadata registry +- Hooks system +- Actions system +- Validation engine +- Repository pattern +- Formula engine +- AI integration + +The `ObjectQLEngine` from `@objectstack/objectql` is a **simpler, lightweight** implementation suitable for: + +- Basic CRUD operations +- Simple driver management +- Minimal runtime overhead + +### Why Type-Only Exports? + +The `@objectstack/objectql` package currently has a configuration issue where it points to source files instead of compiled dist files. To avoid runtime errors, we use **type-only imports** which provide TypeScript type checking without executing the runtime code. + +## Usage + +### Using the Full-Featured ObjectQL (Recommended) + +```typescript +import { ObjectQL } from '@objectql/core'; + +const app = new ObjectQL({ + registry: new MetadataRegistry(), + datasources: { default: driver } +}); + +await app.init(); +const ctx = app.createContext({ userId: 'user123' }); +const repo = ctx.object('todo'); +const items = await repo.find({}); +``` + +### Using Type Definitions from Runtime + +```typescript +import type { ObjectStackKernel, SchemaRegistry } from '@objectql/core'; + +// Use types for compile-time checking +function processKernel(kernel: ObjectStackKernel) { + // Your code here +} +``` + +## Migration Path + +If you want to use the simpler `@objectstack/objectql` implementation: + +1. Install it directly: `npm install @objectstack/objectql` +2. Import from the package: `import { ObjectQL } from '@objectstack/objectql'` +3. Note: Ensure the package is properly built before use + +## Compatibility + +- **@objectstack/spec@0.1.2**: Introduces `searchable` field requirement on FieldConfig +- **Backward Compatible**: All existing ObjectQL APIs remain unchanged +- **Tests**: 236 tests pass successfully, confirming backward compatibility + +## Future Plans + +Once the `@objectstack/objectql` package configuration is fixed, we may: + +1. Use it as a base class for our ObjectQL implementation +2. Move framework-specific features to plugins +3. Provide both lightweight and full-featured options + +## Related Documentation + +- [ObjectQL Types](../types/README.md) +- [ObjectQL Platform Node](../platform-node/README.md) +- [@objectstack/spec on npm](https://www.npmjs.com/package/@objectstack/spec) +- [@objectstack/runtime on npm](https://www.npmjs.com/package/@objectstack/runtime) diff --git a/packages/foundation/core/package.json b/packages/foundation/core/package.json index 6eb76bfa..f7a3161e 100644 --- a/packages/foundation/core/package.json +++ b/packages/foundation/core/package.json @@ -23,7 +23,9 @@ }, "dependencies": { "@objectql/types": "workspace:*", - "@objectstack/spec": "^0.1.1", + "@objectstack/spec": "^0.1.2", + "@objectstack/runtime": "^0.1.1", + "@objectstack/objectql": "^0.1.1", "js-yaml": "^4.1.0", "openai": "^4.28.0" }, diff --git a/packages/foundation/core/src/index.ts b/packages/foundation/core/src/index.ts index 0ba6aca3..775dc154 100644 --- a/packages/foundation/core/src/index.ts +++ b/packages/foundation/core/src/index.ts @@ -6,6 +6,12 @@ * LICENSE file in the root directory of this source tree. */ +// Re-export types from @objectstack packages for API compatibility +// Note: Using type-only imports to avoid runtime issues with @objectstack/objectql package configuration +export type { ObjectStackKernel, ObjectStackRuntimeProtocol } from '@objectstack/runtime'; +export type { ObjectQL as ObjectQLEngine, SchemaRegistry } from '@objectstack/objectql'; + +// Export our enhanced runtime components (actual implementations) export * from './repository'; export * from './app'; diff --git a/packages/foundation/core/src/util.ts b/packages/foundation/core/src/util.ts index 0fd33e8a..5ab2bd77 100644 --- a/packages/foundation/core/src/util.ts +++ b/packages/foundation/core/src/util.ts @@ -117,7 +117,8 @@ export function convertIntrospectedSchemaToObjects( type: 'lookup', reference_to: foreignKey.referencedTable, label: toTitleCase(column.name), - required: !column.nullable + required: !column.nullable, + searchable: false }; } else { // Regular field @@ -129,7 +130,8 @@ export function convertIntrospectedSchemaToObjects( name: column.name, type: fieldType, label: toTitleCase(column.name), - required: !column.nullable + required: !column.nullable, + searchable: false }; // Add unique constraint diff --git a/packages/foundation/types/package.json b/packages/foundation/types/package.json index 1ff6f460..2e2d3e58 100644 --- a/packages/foundation/types/package.json +++ b/packages/foundation/types/package.json @@ -27,7 +27,7 @@ "test": "jest --passWithNoTests" }, "dependencies": { - "@objectstack/spec": "^0.1.1" + "@objectstack/spec": "^0.1.2" }, "devDependencies": { "ts-json-schema-generator": "^2.4.0" diff --git a/packages/foundation/types/src/field.ts b/packages/foundation/types/src/field.ts index 1ed0b8be..175f4568 100644 --- a/packages/foundation/types/src/field.ts +++ b/packages/foundation/types/src/field.ts @@ -125,7 +125,7 @@ export interface FieldOption { * All other protocol properties (description, defaultValue, maxLength, minLength, precision, scale, min, max, * reference, referenceFilters, writeRequiresMasterRead, expression, formula, summaryOperations) are inherited as-is. */ -export interface FieldConfig extends Omit { +export interface FieldConfig extends Omit { /** Field name (inferred from Record key when used in ObjectConfig.fields) */ name?: string; @@ -147,6 +147,9 @@ export interface FieldConfig extends Omit=10'} deprecated: This functionality has been moved to @npmcli/fs - '@objectstack/spec@0.1.1': - resolution: {integrity: sha512-gBeC7PiNxhz2UytY6MHmqB7i13FfRq/xrTXWkM8aobhDkd4REI9DnigaKJctmpuJumc5GWLG9lZgb2voj1rEFg==} + '@objectstack/objectql@0.1.1': + resolution: {integrity: sha512-oVWUOWU7g7j12jY4r8XlLF6yyFf0kiWzSLgm3dRot8/w0/cyLsq9fc+7Dnm/xx9MZwbzXrLBDu9DPxPVVsn3Ng==} + + '@objectstack/runtime@0.1.1': + resolution: {integrity: sha512-uTDwIz3JdnOmLNfrrkRYQJSlNoVGZ7e9T6EcvdUzCPA9Y3jZpi3vXQ8Y30HvT6MVFXdm+P1U2XxkidbwHgOKfg==} + + '@objectstack/spec@0.1.2': + resolution: {integrity: sha512-xnGZV8ND9YnMKHURV5+iOiUQhqGpll95v5Wz9Kgw0rKGd6V6BlvAcl2S56EF8YIK+khZAqWiE4RqrOIXDKoRCw==} engines: {node: '>=18.0.0'} + '@objectstack/types@0.1.1': + resolution: {integrity: sha512-XGkoSfxZvsa2l3LCSMr6XzN8CuxfotbFhICaMgqY746wF41WajZsYJIlQe/4WC9ob9dhBREVdMVbgZlGlh+zjQ==} + '@paralleldrive/cuid2@2.3.1': resolution: {integrity: sha512-XO7cAxhnTZl0Yggq6jOgjiOHhbgcO4NqFqwSmQpjK3b6TEE6Uj/jfSk6wzYyemh3+I0sHirKSetjQwn5cZktFw==} @@ -9632,10 +9647,24 @@ snapshots: rimraf: 3.0.2 optional: true - '@objectstack/spec@0.1.1': + '@objectstack/objectql@0.1.1': + dependencies: + '@objectstack/spec': 0.1.2 + + '@objectstack/runtime@0.1.1': + dependencies: + '@objectstack/objectql': 0.1.1 + '@objectstack/spec': 0.1.2 + '@objectstack/types': 0.1.1 + + '@objectstack/spec@0.1.2': dependencies: zod: 3.25.76 + '@objectstack/types@0.1.1': + dependencies: + '@objectstack/spec': 0.1.2 + '@paralleldrive/cuid2@2.3.1': dependencies: '@noble/hashes': 1.8.0