@objectstack/objectql 3.0.3 → 3.0.4

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/objectql@3.0.3 build /home/runner/work/spec/spec/packages/objectql
+> @objectstack/objectql@3.0.4 build /home/runner/work/spec/spec/packages/objectql
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.js     81.23 KB
-CJS dist/index.js.map 161.10 KB
-CJS ⚡️ Build success in 124ms
-ESM dist/index.mjs     79.69 KB
-ESM dist/index.mjs.map 160.22 KB
-ESM ⚡️ Build success in 126ms
+ESM dist/index.mjs     82.74 KB
+ESM dist/index.mjs.map 169.75 KB
+ESM ⚡️ Build success in 118ms
+CJS dist/index.js     84.46 KB
+CJS dist/index.js.map 171.04 KB
+CJS ⚡️ Build success in 116ms
 DTS Build start
-DTS ⚡️ Build success in 10876ms
-DTS dist/index.d.mts 66.76 KB
-DTS dist/index.d.ts  66.76 KB
+DTS ⚡️ Build success in 11554ms
+DTS dist/index.d.mts 70.34 KB
+DTS dist/index.d.ts  70.34 KB

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @objectstack/objectql
 
+## 3.0.4
+
+### Patch Changes
+
+- 437b0b8: feat(objectql): add utility functions, introspection types, and kernel factory
+
+  Upstream key functionality from downstream `@objectql/core` to enable its future deprecation:
+
+  - **Introspection types**: `IntrospectedSchema`, `IntrospectedTable`, `IntrospectedColumn`, `IntrospectedForeignKey`
+  - **Utility functions**: `toTitleCase()`, `convertIntrospectedSchemaToObjects()`
+  - **Kernel factory**: `createObjectQLKernel()` with `ObjectQLKernelOptions`
+
+- Updated dependencies [d738987]
+  - @objectstack/spec@3.0.4
+  - @objectstack/core@3.0.4
+  - @objectstack/types@3.0.4
+
 ## 3.0.3
 
 ### Patch Changes

package/README.md

@@ -8,16 +8,109 @@ The **Data Engine** for ObjectStack. It acts as a semantic layer between your ap
 - **Schema Validation**: Enforces Zod schemas defined in `@objectstack/spec`.
 - **Query Resolution**: Translates ObjectStack queries into driver-specific commands.
 - **Driver Architecture**: Pluggable storage (Memory, MongoDB, SQL, etc.).
+- **Schema Registry**: Centralized object/FQN management with multi-package ownership model.
+- **Kernel Factory**: One-liner kernel bootstrap with `createObjectQLKernel()`.
+- **Database Introspection**: Convert existing database schemas into ObjectStack metadata via `convertIntrospectedSchemaToObjects()`.
+- **Metadata Facade**: Injectable `IMetadataService`-compatible wrapper over SchemaRegistry.
 
 ## Usage
 
+### Querying Data
+
 ```typescript
 import { ObjectQL } from '@objectstack/objectql';
 
-// Querying data
 const engine = kernel.getService('objectql');
 const users = await engine.find('user', {
     where: { role: 'admin' },
     top: 10
 });
 ```
+
+### Kernel Factory
+
+Create a fully wired ObjectKernel in one call:
+
+```typescript
+import { createObjectQLKernel } from '@objectstack/objectql';
+
+const kernel = await createObjectQLKernel({
+  plugins: [myDriverPlugin, myAuthPlugin],
+});
+await kernel.bootstrap();
+```
+
+### Database Introspection
+
+Convert existing database tables into ObjectStack object definitions:
+
+```typescript
+import { convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
+
+const schema = await driver.introspectSchema();
+const objects = convertIntrospectedSchemaToObjects(schema, {
+  excludeTables: ['migrations', '_prisma_migrations'],
+});
+
+for (const obj of objects) {
+  engine.registerObject(obj);
+}
+```
+
+### Schema Registry
+
+```typescript
+import { SchemaRegistry, computeFQN } from '@objectstack/objectql';
+
+// Register an object under a namespace
+SchemaRegistry.registerObject(taskDef, 'com.acme.todo', 'todo');
+
+// Resolve FQN
+computeFQN('todo', 'task'); // => 'todo__task'
+computeFQN('base', 'user'); // => 'user' (reserved namespace)
+```
+
+## Exported Components
+
+| Export | Description |
+| :--- | :--- |
+| `ObjectQL` | Data engine implementing `IDataEngine` |
+| `ObjectRepository` | Scoped repository bound to object + context |
+| `ScopedContext` | Identity-scoped execution context with `object()` accessor |
+| `SchemaRegistry` | Global schema registry (FQN, ownership, package management) |
+| `MetadataFacade` | Async `IMetadataService`-compatible wrapper |
+| `ObjectQLPlugin` | Kernel plugin that registers ObjectQL services |
+| `ObjectStackProtocolImplementation` | Protocol implementation shim |
+| `createObjectQLKernel()` | Async factory returning a pre-wired `ObjectKernel` |
+| `toTitleCase()` | Convert `snake_case` to `Title Case` |
+| `convertIntrospectedSchemaToObjects()` | DB schema → `ServiceObject[]` converter |
+
+### Introspection Types
+
+| Type | Description |
+| :--- | :--- |
+| `IntrospectedSchema` | Top-level schema with `tables` map |
+| `IntrospectedTable` | Table metadata (columns, foreign keys, primary keys) |
+| `IntrospectedColumn` | Column metadata (name, type, nullable, maxLength, …) |
+| `IntrospectedForeignKey` | Foreign key relationship metadata |
+
+## Migrating from `@objectql/core`
+
+If you are migrating from the downstream `@objectql/core` package, see the
+[Migration Guide](../../content/docs/guides/objectql-migration.mdx) for
+step-by-step instructions.
+
+**Quick summary:**
+
+```diff
+- import { ObjectQL, SchemaRegistry, ObjectRepository } from '@objectql/core';
+- import { createObjectQLKernel } from '@objectql/core';
+- import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectql/core';
++ import { ObjectQL, SchemaRegistry, ObjectRepository } from '@objectstack/objectql';
++ import { createObjectQLKernel } from '@objectstack/objectql';
++ import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
+```
+
+## License
+
+Apache-2.0 © ObjectStack

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import * as _objectstack_spec_data from '@objectstack/spec/data';
 import { ServiceObject, ObjectOwnership, HookContext, QueryAST, DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineCountOptions, DataEngineAggregateOptions } from '@objectstack/spec/data';
 import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
-import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext } from '@objectstack/core';
+import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 
 /**
  * XState-inspired State Machine Protocol
@@ -1724,4 +1724,119 @@ declare class ObjectQLPlugin implements Plugin {
     private loadMetadataFromService;
 }
 
-export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type HookEntry, type HookHandler, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, ScopedContext, computeFQN, parseFQN };
+/**
+ * Options for creating an ObjectQL Kernel.
+ */
+interface ObjectQLKernelOptions {
+    /**
+     * Additional plugins to register with the kernel.
+     */
+    plugins?: Plugin[];
+}
+/**
+ * Convenience factory for creating an ObjectQL-ready kernel.
+ *
+ * Creates an ObjectKernel pre-configured with the ObjectQLPlugin
+ * (data engine, schema registry, protocol implementation) plus any
+ * additional plugins provided.
+ *
+ * @example
+ * ```typescript
+ * import { createObjectQLKernel } from '@objectstack/objectql';
+ *
+ * const kernel = createObjectQLKernel({
+ *   plugins: [myDriverPlugin, myAuthPlugin],
+ * });
+ * await kernel.bootstrap();
+ * ```
+ */
+declare function createObjectQLKernel(options?: ObjectQLKernelOptions): Promise<ObjectKernel>;
+
+/**
+ * Column metadata from database introspection.
+ */
+interface IntrospectedColumn {
+    /** Column name */
+    name: string;
+    /** Native database type (e.g., 'varchar', 'integer', 'timestamp') */
+    type: string;
+    /** Whether the column is nullable */
+    nullable: boolean;
+    /** Default value if any */
+    defaultValue?: unknown;
+    /** Whether this is a primary key */
+    isPrimary?: boolean;
+    /** Whether this column has a unique constraint */
+    isUnique?: boolean;
+    /** Maximum length for string types */
+    maxLength?: number;
+}
+/**
+ * Foreign key relationship metadata.
+ */
+interface IntrospectedForeignKey {
+    /** Column name in the source table */
+    columnName: string;
+    /** Referenced table name */
+    referencedTable: string;
+    /** Referenced column name */
+    referencedColumn: string;
+    /** Constraint name */
+    constraintName?: string;
+}
+/**
+ * Table metadata from database introspection.
+ */
+interface IntrospectedTable {
+    /** Table name */
+    name: string;
+    /** List of columns */
+    columns: IntrospectedColumn[];
+    /** List of foreign key relationships */
+    foreignKeys: IntrospectedForeignKey[];
+    /** Primary key columns */
+    primaryKeys: string[];
+}
+/**
+ * Complete database schema introspection result.
+ */
+interface IntrospectedSchema {
+    /** Map of table name to table metadata */
+    tables: Record<string, IntrospectedTable>;
+}
+/**
+ * Convert a snake_case or plain string to Title Case.
+ *
+ * @example
+ * toTitleCase('first_name')   // => 'First Name'
+ * toTitleCase('project_task') // => 'Project Task'
+ */
+declare function toTitleCase(str: string): string;
+/**
+ * Convert an introspected database schema to ObjectStack object definitions.
+ *
+ * This allows using existing database tables without manually defining metadata.
+ *
+ * @param introspectedSchema - The schema returned from driver.introspectSchema()
+ * @param options            - Optional filtering / conversion settings
+ * @returns Array of ServiceObject definitions that can be registered with ObjectQL
+ *
+ * @example
+ * ```typescript
+ * const schema = await driver.introspectSchema();
+ * const objects = convertIntrospectedSchemaToObjects(schema);
+ * for (const obj of objects) {
+ *   engine.registerObject(obj);
+ * }
+ * ```
+ */
+declare function convertIntrospectedSchemaToObjects(introspectedSchema: IntrospectedSchema, options?: {
+    /** Tables to exclude from conversion */
+    excludeTables?: string[];
+    /** Tables to include (if specified, only these will be converted) */
+    includeTables?: string[];
+    /** Whether to skip system columns like id, created_at, updated_at (default: true) */
+    skipSystemColumns?: boolean;
+}): ServiceObject[];
+
+export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type HookEntry, type HookHandler, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, ScopedContext, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, parseFQN, toTitleCase };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import * as _objectstack_spec_data from '@objectstack/spec/data';
 import { ServiceObject, ObjectOwnership, HookContext, QueryAST, DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineCountOptions, DataEngineAggregateOptions } from '@objectstack/spec/data';
 import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
-import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext } from '@objectstack/core';
+import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 
 /**
  * XState-inspired State Machine Protocol
@@ -1724,4 +1724,119 @@ declare class ObjectQLPlugin implements Plugin {
     private loadMetadataFromService;
 }
 
-export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type HookEntry, type HookHandler, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, ScopedContext, computeFQN, parseFQN };
+/**
+ * Options for creating an ObjectQL Kernel.
+ */
+interface ObjectQLKernelOptions {
+    /**
+     * Additional plugins to register with the kernel.
+     */
+    plugins?: Plugin[];
+}
+/**
+ * Convenience factory for creating an ObjectQL-ready kernel.
+ *
+ * Creates an ObjectKernel pre-configured with the ObjectQLPlugin
+ * (data engine, schema registry, protocol implementation) plus any
+ * additional plugins provided.
+ *
+ * @example
+ * ```typescript
+ * import { createObjectQLKernel } from '@objectstack/objectql';
+ *
+ * const kernel = createObjectQLKernel({
+ *   plugins: [myDriverPlugin, myAuthPlugin],
+ * });
+ * await kernel.bootstrap();
+ * ```
+ */
+declare function createObjectQLKernel(options?: ObjectQLKernelOptions): Promise<ObjectKernel>;
+
+/**
+ * Column metadata from database introspection.
+ */
+interface IntrospectedColumn {
+    /** Column name */
+    name: string;
+    /** Native database type (e.g., 'varchar', 'integer', 'timestamp') */
+    type: string;
+    /** Whether the column is nullable */
+    nullable: boolean;
+    /** Default value if any */
+    defaultValue?: unknown;
+    /** Whether this is a primary key */
+    isPrimary?: boolean;
+    /** Whether this column has a unique constraint */
+    isUnique?: boolean;
+    /** Maximum length for string types */
+    maxLength?: number;
+}
+/**
+ * Foreign key relationship metadata.
+ */
+interface IntrospectedForeignKey {
+    /** Column name in the source table */
+    columnName: string;
+    /** Referenced table name */
+    referencedTable: string;
+    /** Referenced column name */
+    referencedColumn: string;
+    /** Constraint name */
+    constraintName?: string;
+}
+/**
+ * Table metadata from database introspection.
+ */
+interface IntrospectedTable {
+    /** Table name */
+    name: string;
+    /** List of columns */
+    columns: IntrospectedColumn[];
+    /** List of foreign key relationships */
+    foreignKeys: IntrospectedForeignKey[];
+    /** Primary key columns */
+    primaryKeys: string[];
+}
+/**
+ * Complete database schema introspection result.
+ */
+interface IntrospectedSchema {
+    /** Map of table name to table metadata */
+    tables: Record<string, IntrospectedTable>;
+}
+/**
+ * Convert a snake_case or plain string to Title Case.
+ *
+ * @example
+ * toTitleCase('first_name')   // => 'First Name'
+ * toTitleCase('project_task') // => 'Project Task'
+ */
+declare function toTitleCase(str: string): string;
+/**
+ * Convert an introspected database schema to ObjectStack object definitions.
+ *
+ * This allows using existing database tables without manually defining metadata.
+ *
+ * @param introspectedSchema - The schema returned from driver.introspectSchema()
+ * @param options            - Optional filtering / conversion settings
+ * @returns Array of ServiceObject definitions that can be registered with ObjectQL
+ *
+ * @example
+ * ```typescript
+ * const schema = await driver.introspectSchema();
+ * const objects = convertIntrospectedSchemaToObjects(schema);
+ * for (const obj of objects) {
+ *   engine.registerObject(obj);
+ * }
+ * ```
+ */
+declare function convertIntrospectedSchemaToObjects(introspectedSchema: IntrospectedSchema, options?: {
+    /** Tables to exclude from conversion */
+    excludeTables?: string[];
+    /** Tables to include (if specified, only these will be converted) */
+    includeTables?: string[];
+    /** Whether to skip system columns like id, created_at, updated_at (default: true) */
+    skipSystemColumns?: boolean;
+}): ServiceObject[];
+
+export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type HookEntry, type HookHandler, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, ScopedContext, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, parseFQN, toTitleCase };

package/dist/index.js

@@ -31,7 +31,10 @@ __export(index_exports, {
   SchemaRegistry: () => SchemaRegistry,
   ScopedContext: () => ScopedContext,
   computeFQN: () => computeFQN,
-  parseFQN: () => parseFQN
+  convertIntrospectedSchemaToObjects: () => convertIntrospectedSchemaToObjects,
+  createObjectQLKernel: () => createObjectQLKernel,
+  parseFQN: () => parseFQN,
+  toTitleCase: () => toTitleCase
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -2460,6 +2463,103 @@ var ObjectQLPlugin = class {
     }
   }
 };
+
+// src/kernel-factory.ts
+var import_core2 = require("@objectstack/core");
+async function createObjectQLKernel(options = {}) {
+  const kernel = new import_core2.ObjectKernel();
+  await kernel.use(new ObjectQLPlugin());
+  if (options.plugins) {
+    for (const plugin of options.plugins) {
+      await kernel.use(plugin);
+    }
+  }
+  return kernel;
+}
+
+// src/util.ts
+function toTitleCase(str) {
+  return str.replace(/_/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function mapDatabaseTypeToFieldType(dbType) {
+  const type = dbType.toLowerCase();
+  if (type.includes("char") || type.includes("varchar") || type.includes("text")) {
+    if (type.includes("text")) return "textarea";
+    return "text";
+  }
+  if (type.includes("int") || type === "integer" || type === "bigint" || type === "smallint") {
+    return "number";
+  }
+  if (type.includes("float") || type.includes("double") || type.includes("decimal") || type.includes("numeric") || type === "real") {
+    return "number";
+  }
+  if (type.includes("bool")) {
+    return "boolean";
+  }
+  if (type.includes("timestamp") || type === "datetime") {
+    return "datetime";
+  }
+  if (type === "date") {
+    return "date";
+  }
+  if (type === "time") {
+    return "time";
+  }
+  if (type === "json" || type === "jsonb") {
+    return "json";
+  }
+  return "text";
+}
+function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
+  const objects = [];
+  const excludeTables = options?.excludeTables || [];
+  const includeTables = options?.includeTables;
+  const skipSystemColumns = options?.skipSystemColumns !== false;
+  for (const [tableName, table] of Object.entries(introspectedSchema.tables)) {
+    if (excludeTables.includes(tableName)) continue;
+    if (includeTables && !includeTables.includes(tableName)) continue;
+    const fields = {};
+    for (const column of table.columns) {
+      if (skipSystemColumns && ["id", "created_at", "updated_at"].includes(column.name)) {
+        continue;
+      }
+      const foreignKey = table.foreignKeys.find((fk) => fk.columnName === column.name);
+      if (foreignKey) {
+        fields[column.name] = {
+          name: column.name,
+          type: "lookup",
+          reference: foreignKey.referencedTable,
+          label: toTitleCase(column.name),
+          required: !column.nullable
+        };
+      } else {
+        const fieldType = mapDatabaseTypeToFieldType(column.type);
+        const field = {
+          name: column.name,
+          type: fieldType,
+          label: toTitleCase(column.name),
+          required: !column.nullable
+        };
+        if (column.isUnique) {
+          field.unique = true;
+        }
+        if (column.maxLength && (fieldType === "text" || fieldType === "textarea")) {
+          field.maxLength = column.maxLength;
+        }
+        if (column.defaultValue != null) {
+          field.defaultValue = column.defaultValue;
+        }
+        fields[column.name] = field;
+      }
+    }
+    objects.push({
+      name: tableName,
+      label: toTitleCase(tableName),
+      fields
+    });
+  }
+  return objects;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_EXTENDER_PRIORITY,
@@ -2473,6 +2573,9 @@ var ObjectQLPlugin = class {
   SchemaRegistry,
   ScopedContext,
   computeFQN,
-  parseFQN
+  convertIntrospectedSchemaToObjects,
+  createObjectQLKernel,
+  parseFQN,
+  toTitleCase
 });
 //# sourceMappingURL=index.js.map