ivy-kit

library0.0.25jsnpmunverified

Ivy Kit (v0.0.25, pre-release, monthly updates) is a CLI migrator tool for Ivy ORM, a fully type-safe ORM for Azure AI Search. It manages Azure AI Search data plane operations—creating, updating, and deploying indexes and indexers—through declarative schema migrations. Unlike generic tools, it integrates tightly with Ivy ORM's TypeScript type system, ensuring schema definitions are type-checked and automatically synced. Ivy Kit handles index lifecycle, validates schema changes against production indexes, and supports rollbacks. It is designed for TypeScript projects using Azure AI Search, with a focus on developer experience and safety.

database devops

npm install ivy-kit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · IVY-KIT

ivy-kit

databasejavascriptv0.0.25

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CLI usage via npx ivy-kit

✓ npx ivy-kit generate

✗ ivy-kit generate (without npx if not installed globally)

Use npx to run without global installation; ensure ivy-orm is installed in the project.

DefineSchema

✓ import { DefineSchema } from 'ivy-orm'

✗ import { DefineSchema } from 'ivy-kit'

DefineSchema is part of ivy-orm, not ivy-kit. Ivy Kit consumes schemas defined with ivy-orm.

MigrationFile

✓ import type { MigrationFile } from 'ivy-kit'

✗ import { MigrationFile } from 'ivy-kit'

MigrationFile is a type, use type import. Requires TypeScript >= 4.5.

Shows how to define a schema with ivy-orm and use ivy-kit CLI to generate and apply migrations to Azure AI Search.

// 1. Install dependencies npm install ivy-orm ivy-kit // 2. Define a schema (e.g., schemas/index.ts) import { DefineSchema } from 'ivy-orm'; export const documentsSchema = DefineSchema({ name: 'documents', fields: [ { name: 'id', type: 'Edm.String', key: true }, { name: 'content', type: 'Edm.String', searchable: true }, { name: 'createdAt', type: 'Edm.DateTimeOffset', filterable: true }, ], suggesters: [{ name: 'sg', searchMode: 'analyzingInfixMatching', sourceFields: ['content'] }] }); // 3. Generate migration // Run: npx ivy-kit generate // 4. Apply migration // Run: npx ivy-kit apply // Note: Requires AZURE_SEARCH_API_KEY and AZURE_SEARCH_ENDPOINT environment variables

Debug

Known issues

gotchaIvy Kit is at version 0.0.25, pre-release. API may change without notice. Not recommended for production without pinning versions.

fix

Pin exact versions in package.json: 'ivy-kit': '0.0.25', 'ivy-orm': '0.0.x'

affects: <1.0.0

breakingMigrations generated in v0.0.23+ are incompatible with earlier versions due to a change in index naming conventions.

fix

Regenerate migrations after upgrading ivy-kit. Delete old migration files and run 'npx ivy-kit generate' again.

affects: >=0.0.23

deprecatedThe '--dry-run' flag is deprecated in v0.0.20 and will be removed in v0.1.0. Use '--validate' instead.

fix

Replace 'npx ivy-kit apply --dry-run' with 'npx ivy-kit apply --validate'

affects: >=0.0.20 <0.1.0

gotchaIvy Kit requires environment variables AZURE_SEARCH_API_KEY and AZURE_SEARCH_ENDPOINT to be set. Missing them causes cryptic errors.

fix

Set env vars in .env file or shell. Ensure AZURE_SEARCH_ENDPOINT includes https:// and no trailing slash.

affects: >=0.0.1

breakingIndexer definitions now require 'parameters' field as of v0.0.18. Older migration files will fail to apply.

fix

Update indexer schemas in ivy-orm to include parameters object. Refer to documentation: https://github.com/ihusemann/ivy-orm#indexer

affects: >=0.0.18

Errors

Common errors & fixes

Error: Cannot find module 'ivy-orm'

ivy-orm is not installed or not in node_modules.

fix

Run: npm install ivy-orm

TypeError: AZURE_SEARCH_API_KEY is not defined

Environment variable for API key is missing.

fix

Set AZURE_SEARCH_API_KEY in your environment or .env file.

Error: Invalid schema: field 'id' must have key: true

Schema is missing a key field definition.

fix

Add a field with key: true in your schema definition.

Error: Migration 001 already applied. Use --force to reapply.

Trying to apply an already applied migration without force flag.

fix

Use: npx ivy-kit apply --force (be careful as it may overwrite indexes).

Upgrade

Version history

0.0.25latest on npm

Audit

Dependencies

ivy-ormrequiredCore ORM required for schema definitions and migration generation

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/ihusemann/ivy-orm ↗

packageivy-kit ↗

homepagehttps://github.com/ihusemann/ivy-orm#readme ↗