Merge pull request #268 from rush-db/feat/importJson-separation-and-export-fixes

 createMany & importJson separation plus minor export and import impr…

Author: 1pxone

.changeset/real-pianos-wash.md

@@ -0,0 +1,10 @@
+---
+'@rushdb/javascript-sdk': minor
+'@rushdb/mcp-server': minor
+'rushdb-dashboard': minor
+'rushdb-core': minor
+'rushdb-website': minor
+'rushdb-docs': minor
+---
+
+createMany & importJson separation plus minor export and import improvements

.gitignore

@@ -1,5 +1,6 @@
 node_modules
 dist
+build
 *.log
 *.tgz
 .env

README.md

@@ -160,7 +160,7 @@ import RushDB from '@rushdb/javascript-sdk';
 const db = new RushDB("RUSHDB_API_KEY");
 
 // Push data with automatic relationship creation
-await db.records.createMany({
+await db.records.importJson({
    label: "COMPANY",
    payload: {
       name: 'Google LLC',

docs/docs/index.mdx

@@ -68,7 +68,7 @@ Get instant guidance through our **[RushDB Docs Chat](https://chatgpt.com/g/g-67
   const db = new RushDB("RUSHDB_API_KEY");
 
   // Push data with any structure you need
-  await db.records.createMany({
+  await db.records.importJson({
     label: "PRODUCT",
     data: {
       title: "Ergonomic Chair",

docs/docs/typescript-sdk/introduction.md

@@ -57,7 +57,7 @@ const db = new RushDB("RUSHDB_API_KEY");
 
 // Push any data, and RushDB will automatically flatten it into Records
 // and establish relationships between them accordingly.
-await db.records.createMany({
+await db.records.importJson({
   label: "COMPANY",
   data: {
     name: 'Google LLC',
@@ -164,7 +164,7 @@ const db = new RushDB('RUSHDB_API_KEY', {
 
 ## SDK Architecture
 
-The RushDB SDK uses a consistent approach for accessing the RushDB API instance across all SDK components. Classes like `Transaction`, `DBRecordInstance`, `DBRecordsArrayInstance` and `Model` all use the static `RushDB.init()` method to obtain the API instance, ensuring a uniform pattern throughout the SDK.
+The RushDB SDK uses a consistent approach for accessing the RushDB API instance across all SDK components. Classes like `Transaction`, `DBRecordInstance`, `DBRecordsArrayInstance` and `Model` all use the static `RushDB.getInstance()` method to obtain the API instance, ensuring a uniform pattern throughout the SDK.
 
 This architecture provides several benefits:
 
@@ -177,7 +177,7 @@ Example of the implementation pattern:
 ```typescript
 // Internal implementation example
 async someMethod(param: string): Promise<ApiResponse> {
-  const instance = await RushDB.init()  // Get the RushDB instance
+  const instance = RushDB.getInstance()  // Get the RushDB instance
   return await instance.someApi.someMethod(param)  // Use the instance to make API calls
 }
 ```

docs/docs/typescript-sdk/models.md

@@ -149,23 +149,15 @@ export type UserSearchQuery = SearchQuery<typeof UserModel.schema>;
 
 ### Model Implementation Architecture
 
-The `Model` class uses the same architectural pattern as other SDK components like `Transaction` and `DBRecordInstance`. It uses the static `RushDB.init()` method to access the API:
+The `Model` class uses the same architectural pattern as other SDK components like `Transaction` and `DBRecordInstance`. It uses the static `RushDB.getInstance()` method to access the API:
 
 ```typescript
 // Internal implementation pattern (from model.ts)
 async someMethod(params) {
-  const instance = await this.getRushDBInstance()
+  const instance = RushDB.getInstance()
   return await instance.someApi.someMethod(params)
 }
 
-// getRushDBInstance method in Model class
-public async getRushDBInstance(): Promise<RushDB> {
-  const instance = RushDB.getInstance()
-  if (instance) {
-    return await RushDB.init()
-  }
-  throw new Error('No RushDB instance found. Please create a RushDB instance first: new RushDB("RUSHDB_API_KEY")')
-}
 ```
 
 This architecture ensures consistent API access across all SDK components.
@@ -248,8 +240,8 @@ import RushDB from '@rushdb/javascript-sdk';
 export const db = new RushDB('RUSHDB_API_KEY');
 
 // You can also export a helper function to access the instance
-export const getRushDBInstance = async () => {
-  return await RushDB.init();
+export const getRushDBInstance = () => {
+  return RushDB.getInstance();
 };
 ```
 
@@ -351,82 +343,9 @@ await AuthorModel.detach({
 
 ## Advanced TypeScript Support
 
-When working with RushDB SDK, achieving perfect TypeScript contracts ensures a seamless development experience. TypeScript's strong typing system allows for precise autocomplete suggestions and error checking, particularly when dealing with complex queries and nested models. This section will guide you on how to enhance TypeScript support by defining comprehensive type definitions for your models.
-
-### Defining Comprehensive TypeScript Types
-
-To fully leverage TypeScript's capabilities, you can define types that include all schemas you've registered with `Model`. This will allow you to perform complex queries with nested model fields, ensuring type safety and better autocompletion.
-
-#### Step 1: Create Models with Model
-
-First, define your models using `Model`:
-```typescript
-import { Model } from '@rushdb/javascript-sdk'
-
-// Create models
-const AuthorModel = new Model('author', {
-  name: { type: 'string' },
-  email: { type: 'string', unique: true }
-});
-
-const PostModel = new Model('post', {
-  created: { type: 'datetime', default: () => new Date().toISOString() },
-  title: { type: 'string' },
-  content: { type: 'string' },
-  rating: { type: 'number' }
-});
-
-const BlogModel = new Model('blog', {
-  title: { type: 'string' },
-  description: { type: 'string' }
-});
-```
-
-#### Step 2: Create an Exportable Type for All Schemas
-
-Next, create an exportable type that includes all the schemas defined in your application:
-```typescript
-export type MyModels = {
-  author: typeof AuthorModel.schema
-  post: typeof PostModel.schema
-  blog: typeof BlogModel.schema
-}
-```
-
-#### Step 3: Extend the Models Interface
-
-Add this type declaration to your project. This ensures that RushDB SDK is aware of your models:
-```typescript
-// index.d.ts or other d.ts file added to include in tsconfig.json
-
-import { MyModels } from './types';
-
-declare module '@rushdb/javascript-sdk' {
-  export interface Models extends MyModels {}
-}
-```
-
-### Example Usage: Complex Queries with Type Safety
-
-By following these steps, you can now write complex queries with confidence, knowing that TypeScript will help you avoid errors and provide accurate autocomplete suggestions. Here's an example demonstrating how you can leverage this setup:
-
-```typescript
-const query = await db.records.find({
-  labels: ['post'],
-  where: {
-    author: {
-      name: { $contains: 'John' }, // Checking if the author's name contains 'John'
-      post: {
-        rating: { $gt: 5 } // Posts with rating greater than 5
-      }
-    }
-  }
-});
-```
-
-In this example, the `db.records.find` method allows you to use nested fields in the `where` condition, thanks to the enhanced TypeScript definitions. This ensures that you can easily and accurately query your data, leveraging the full power of TypeScript.
+For a complete, up-to-date guide on configuring declaration merging, path aliases, and schema-aware intellisense (including typed related queries), see the Model reference: [TypeScript: extend SDK types for schema-aware suggestions](./typescript-reference/Model#typescript-extend-sdk-types-for-schema-aware-suggestions).
 
-By defining comprehensive type definitions for your models and extending the `Models` interface, you can significantly enhance your TypeScript support when working with RushDB SDK. This approach ensures type safety, better autocompletion, and a more efficient development experience.
+Note on result typing with aggregations/grouping: when you use `aggregate` or `groupBy`, the result shape can differ from your schema. You can augment the instance type as `typeof Model.recordInstance & { data: T }` to describe the returned payload. See the dedicated explanation and examples in the Model reference, and the concepts for [Aggregations](../concepts/search/aggregations) and [Grouping](../concepts/search/group-by).
 
 ## Working with Transactions
 

docs/docs/typescript-sdk/records/create-records.md

@@ -165,9 +165,9 @@ Each property draft object supports the following properties:
 
 ## Creating Multiple Records
 
-When you need to create multiple records in a single operation, use the `records.createMany` method.
+When you need to create multiple flat records (CSV-like rows) in a single operation, use the `records.createMany` method. For nested or complex JSON, use `records.importJson`.
 
-### Using RushDB's `createMany()` Method
+### Using RushDB's `createMany()` Method (flat rows only)
 
 ```typescript
 const authors = await db.records.createMany({
@@ -206,14 +206,58 @@ console.log(authors);
 #### Parameters
 
 - `label`: The [label](../../concepts/labels.md)/type for all records
-- `data`: Object (nested too) or an array of objects, each representing a record to create
+- `data`: An object or array of objects, each a flat record (no nested objects/arrays)
 - `options` (optional): Configuration options for record creation:
   - `suggestTypes` (boolean, default: `true`): When true, automatically infers data types for [properties](../../concepts/properties.md)
   - `castNumberArraysToVectors` (boolean, default: `false`): When true, converts numeric arrays to vector type
   - `convertNumericValuesToNumbers` (boolean, default: `false`): When true, converts string numbers to number type
   - `capitalizeLabels` (bool): When true, converts all labels to uppercase
   - `relationshipType` (str): Default relationship type between nodes
   - `returnResult` (bool, default: `false`): When true, returns imported records in response
+  - Throws if any record contains nested objects/arrays. Use `records.importJson` for that.
+
+  ### Using RushDB's `importJson()` Method (nested JSON)
+
+  Use `importJson` for nested objects, arrays of nested objects, or hash-map like payloads.
+
+  Signature:
+
+  ```ts
+  db.records.importJson({ data, label?: string, options?: ImportOptions }, tx?)
+  ```
+
+  Behavior:
+  - If `label` is provided, it's used for the import.
+  - If `label` is omitted, the input must be an object with a single top-level key whose name becomes the label, e.g. `{ ITEM: [ {...}, {...} ] }`.
+  - If `label` is omitted and the object has multiple top-level keys (e.g. `{ some: 'key', data: 1, nested: { level: 2 } }`), an error is thrown.
+
+  Multiple top-level keys:
+  - Without `label`: not allowed — importJson requires a single top-level key to infer the label and will throw.
+  - With `label`: allowed — the provided `label` becomes the root label; the multiple keys are treated as nested structure under that root.
+  - If you want each top-level key to become its own label root, call `importJson` separately per key or pass single-key objects per call.
+
+  Examples:
+  - OK (label inferred):
+    ```json
+    { "ITEM": [ { /*...*/ }, { /*...*/ } ] }
+    ```
+  - OK (label inferred with object):
+    ```json
+    { "ITEM": { /*...*/ } }
+    ```
+  - OK with explicit label (multiple top-level keys):
+    ```json
+    { "ITEM": { /*...*/ }, "PRODUCT": { /*...*/ } }
+    ```
+    Call as: `db.records.importJson({ label: 'INVENTORY', data: { ITEM: {...}, PRODUCT: {...} } })`
+  - Will throw without label (multiple top-level keys):
+    ```json
+    { "ITEM": { /*...*/ }, "PRODUCT": { /*...*/ } }
+    ```
+  - Will throw without label (mixed keys):
+    ```json
+    { "ITEM": { /*...*/ }, "notNestedProp": "12" }
+    ```
 - `transaction` (optional): A [transaction](../../concepts/transactions.mdx) object or string to include the operation within a transaction
 
 #### Returns