Build and maintain TypeScript ORM with type-safe TypeQL abstractions for TypeDB database operations
Type-safe TypeScript ORM for TypeDB with Django-style query patterns and full TypeQL abstraction.
This skill guides you in developing and maintaining type-bridge-ts, a TypeScript ORM that provides type-safe abstractions over TypeDB's TypeQL query language. It supports all TypeDB value types, entity/relation models, CRUD operations, and expression-based queries.
1. **Attribute System** (`src/attribute/`)
- Abstract base class for type-safe attributes
- 9 concrete implementations for TypeDB value types
- Flags for cardinality, key constraints, and ownership
2. **Model System** (`src/models/`)
- `TypeDBType` base class
- `Entity` and `Relation` classes for schema definition
- Role system for relation participation
- Static registration of owned attributes
3. **CRUD System** (`src/crud/`)
- `EntityManager` and `RelationManager` for data operations
- `EntityQuery` and `RelationQuery` for filtering and retrieval
- Django-style lookup operators (gt, gte, lt, lte, contains, in, etc.)
4. **Expression System** (`src/expressions/`)
- Type-safe query expressions
- Comparison, string, and aggregate operations
- Composable boolean expressions
5. **Query Builder** (`src/query.ts`)
- Low-level TypeQL query construction
- Reserved word validation
```bash
npm install
npm run typecheck
npm test
```
When adding or modifying attribute types:
Example:
```typescript
class CustomAttribute extends Attribute<CustomType> {
static override flags = new AttributeFlags({
name: 'custom-type',
// Add constraints as needed
});
}
```
Entity and Relation definitions follow this pattern:
```typescript
class MyEntity extends Entity {
static override flags = new TypeFlags({ name: 'my-entity' });
// Declare properties
declare myAttribute: MyAttributeType;
// Register owned attributes
static {
this.ownedAttributes = new Map([
['myAttribute', {
typ: MyAttributeType,
flags: new AttributeFlags({ isKey: true })
}],
]);
}
}
```
Key points:
Managers handle all database operations:
```typescript
const manager = MyEntity.manager(db);
// Insert
await manager.insert(new MyEntity({ /* ... */ }));
// Query with filters
const results = await manager.filter({
attribute__gt: value,
another__contains: 'text'
});
// Update
await manager.update(instance, { attribute: newValue });
// Delete
await manager.delete(instance);
```
Use expressions for complex queries:
```typescript
const query = manager.query()
.where(MyAttribute.exact('value'))
.or(MyAttribute.contains('partial'))
.limit(10)
.offset(20);
const results = await query.fetch();
```
Structure tests by component:
Run tests with:
```bash
npm test # All tests
npm test -- attribute/ # Specific directory
npm test -- CustomTest # Specific test file
```
Always validate against TypeQL reserved words:
```typescript
import { validateIdentifier } from './validation';
validateIdentifier('myIdentifier'); // Throws if reserved
```
Reserved word list maintained in `src/reserved-words.ts`.
```typescript
class Employment extends Relation {
static override flags = new TypeFlags({ name: 'employment' });
declare salary: Salary;
static {
this.roles = {
employer: Company,
employee: Person,
};
this.ownedAttributes = new Map([
['salary', { typ: Salary, flags: new AttributeFlags() }],
]);
}
}
```
```typescript
// Combining filters
const adults = await Person.manager(db).filter({
age__gte: 18,
age__lt: 65,
status__in: ['active', 'pending'],
});
// Using expressions
const query = Person.manager(db).query()
.where(
Age.gte(18).and(Age.lt(65))
);
```
```typescript
// Single value (default)
static flags = new AttributeFlags({ card: Card.ONE });
// Optional
static flags = new AttributeFlags({ card: Card.ZERO_OR_ONE });
// Multiple values
static flags = new AttributeFlags({ card: Card.MANY });
```
1. **Static Blocks**: Use `static {}` for attribute registration (runs once per class load)
2. **Declare Syntax**: Use `declare` for properties defined via ownedAttributes
3. **Type Safety**: Leverage TypeScript's type system for compile-time validation
4. **Async/Await**: All database operations return Promises
1. **Reserved Word Errors**: Check `src/reserved-words.ts` and use `validateIdentifier()`
2. **Type Mismatches**: Ensure attribute types match TypeDB schema
3. **Connection Failures**: Verify TypeDB server is running and address is correct
4. **Query Errors**: Check TypeQL syntax in generated queries using `query.toString()`
Enable verbose logging:
```typescript
const db = new Database({
address: 'localhost:1729',
database: 'mydb',
// Add logging as needed
});
```
Maintain documentation in `docs/`:
Required packages:
Install with:
```bash
npm install typedb-driver-http typescript
```
When submitting changes:
1. Run full test suite: `npm test`
2. Type check: `npm run typecheck`
3. Build: `npm run build`
4. Update relevant documentation in `docs/`
5. Add tests for new features
6. Follow existing code style and patterns
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/typedb-typescript-orm-development/raw