* 💳 fix: Reserve Balance for In-Flight Requests Admit each balance-checked request against the credits that other in-flight requests have not already reserved, and hold its prompt cost on the balance record until the turn settles. Apply a due auto-refill in the same fenced write so one refill window credits exactly once. - data-schemas: reserveBalance / releaseBalanceReservation replace createAutoRefillTransaction; the write is a compare-and-swap on tokenCredits, reservations and lastRefill (no pipeline updates) - balance.reservations is select:false so existing reads never see it - checkBalance returns a reservation handle; BaseClient and the assistants controllers release it once the turn settles - balance.reservationTtlMs bounds how long an unreleased reservation counts (default 30 minutes) * 🧮 refactor: Admit Reservations Without Contention and Record Refills Durably - admission is a conditional $push/$inc against a reservedCredits total, so concurrent admissions of a funded balance commit on their first write - expired reservations are pruned per element with their credits - auto-refill is fenced on every setting its decision reads and leaves a pendingRefill ledger marker in the same write; any later read records the transaction under the fixed id and clears the marker - a missing record is created with $setOnInsert inside reserveBalance - reservation lifecycle moves to packages/api (createBalanceReservations, withBalanceReservations); BaseClient releases once usage is recorded * 🪪 fix: Resolve Each User to One Balance Record - balance records a creator inserts are keyed by the user id, so creators racing on a missing record converge on one document; every balance read and write resolves a user to their oldest record, so existing duplicates stay inert - upsertBalanceFields takes insert-only fields; the balance-config middleware, schedules and lazy initialization pass the starting credit through them so it never overwrites a record another writer created - the auto-refill write is also fenced on reservedCredits - the scheduled-chat balance pre-skip counts reserved credits as unavailable * ⏳ fix: Count Only Unexpired Reservations in Scheduled Balance Checks findBalanceByUser with includeReservedCredits now totals the reservations that have not expired, so a reservation left by a crashed request stops pre-skipping scheduled chats at its expiry instead of when a later reservation write prunes it. * 🔁 fix: Renew Balance Reservations While Their Request Runs A reservation is renewed every half TTL until it is released, so only a reservation whose process stopped expires. Pruning removes a reservation only while it is still expired at the write, so one renewed after the pruning read survives. * 🛟 fix: Keep Reservations Alive Through Renewal Failures and Lost Acks - renewal reschedules itself: every half TTL, capped to the timer range, and a failed renewal retries within a tenth of that window - an admission write that errors removes its possibly committed reservation before rethrowing * 🛑 fix: Hold a Stopped Turn's Reservation Until Its Charge Lands - an aborted turn lets its reservations lapse after a minute (or the TTL) instead of releasing them, so the Stop request's charge lands before the credits are admitted again - balance.reservationTtlMs has a 10 second minimum, enforced in the schema and at runtime, so renewal stays bounded * ↩️ revert: Release a Stopped Turn's Reservation When the Turn Settles An aborted turn releases its reservations when it settles, the same as every other exit, instead of holding them for a fixed lapse window that refused funded requests after every Stop. The minimum reservation TTL stays. * ⏸️ fix: Hold Assistants Reservations Through Background Run Retries An in-progress Assistants run continues in the background after the handler responds; the turn's reservations now stay held until that run settles (createBalanceReservations().holdUntil). * 🔁 fix: Apply an Auto-Refill Once per Admission A refill interval that is due again the moment it is applied, such as a zero interval, let one admission refill repeatedly until the retry bound. Each admission now applies at most one refill, as the previous check did. * 🧹 fix: Prune Expired Reservations in One Write An admission that found expired reservations issued one write per hold, so a backlog left by a stopped process fanned out into as many concurrent writes. The prune is now a single write fenced on every hold it removes; a hold renewed after the read makes the write miss and the admission re-read. * ⏱️ fix: Renew Reservations From Their Stored Expiry The next renewal was scheduled half a TTL after the previous write settled, and the first one half a TTL after the admission returned, so a slow write could let a live hold expire before its renewal. Renewals are now scheduled from the expiry the last write stored. Expired holds are pruned as one bulk write of per-hold fenced updates, so a hold that changed after the read is skipped while the rest are removed, and the admission no longer spends a retry on the whole prune. |
||
|---|---|---|
| .. | ||
| misc | ||
| src | ||
| .gitignore | ||
| babel.config.cjs | ||
| jest.config.mjs | ||
| jest.globalSetup.mjs | ||
| LICENSE | ||
| package.json | ||
| README.md | ||
| tsconfig.build.json | ||
| tsconfig.json | ||
| tsconfig.spec.json | ||
| tsdown.config.mjs | ||
LibreChat Data Schemas Package
This package provides the database schemas, models, types, and methods for LibreChat using Mongoose ODM.
📁 Package Structure
packages/data-schemas/
├── src/
│ ├── schema/ # Mongoose schema definitions
│ ├── models/ # Model factory functions
│ ├── types/ # TypeScript type definitions
│ ├── methods/ # Database operation methods
│ ├── common/ # Shared constants and enums
│ ├── config/ # Configuration files (winston, etc.)
│ └── index.ts # Main package exports
🏗️ Architecture Patterns
1. Schema Files (src/schema/)
Schema files define the Mongoose schema structure. They follow these conventions:
- Naming: Use lowercase filenames (e.g.,
user.ts,accessRole.ts) - Imports: Import types from
~/typesfor TypeScript support - Exports: Export only the schema as default
Example:
import { Schema } from 'mongoose';
import type { IUser } from '~/types';
const userSchema = new Schema<IUser>(
{
name: { type: String },
email: { type: String, required: true },
// ... other fields
},
{ timestamps: true }
);
export default userSchema;
2. Type Definitions (src/types/)
Type files define TypeScript interfaces and types. They follow these conventions:
- Base Type: Define a plain type without Mongoose Document properties
- Document Interface: Extend the base type with Document and
_id - Enums/Constants: Place related enums in the type file or
common/if shared
Example:
import type { Document, Types } from 'mongoose';
export type User = {
name?: string;
email: string;
// ... other fields
};
export type IUser = User &
Document & {
_id: Types.ObjectId;
};
3. Model Factory Functions (src/models/)
Model files create Mongoose models using factory functions. They follow these conventions:
- Function Name:
create[EntityName]Model - Singleton Pattern: Check if model exists before creating
- Type Safety: Use the corresponding interface from types
Example:
import userSchema from '~/schema/user';
import type * as t from '~/types';
export function createUserModel(mongoose: typeof import('mongoose')) {
return mongoose.models.User || mongoose.model<t.IUser>('User', userSchema);
}
4. Database Methods (src/methods/)
Method files contain database operations for each entity. They follow these conventions:
- Function Name:
create[EntityName]Methods - Return Type: Export a type for the methods object
- Operations: Include CRUD operations and entity-specific queries
Example:
import type { Model } from 'mongoose';
import type { IUser } from '~/types';
export function createUserMethods(mongoose: typeof import('mongoose')) {
async function findUserById(userId: string): Promise<IUser | null> {
const User = mongoose.models.User as Model<IUser>;
return await User.findById(userId).lean();
}
async function createUser(userData: Partial<IUser>): Promise<IUser> {
const User = mongoose.models.User as Model<IUser>;
return await User.create(userData);
}
return {
findUserById,
createUser,
// ... other methods
};
}
export type UserMethods = ReturnType<typeof createUserMethods>;
5. Main Exports (src/index.ts)
The main index file exports:
createModels()- Factory function for all modelscreateMethods()- Factory function for all methods- Type exports from
~/types - Shared utilities and constants
🚀 Adding a New Entity
To add a new entity to the data-schemas package, follow these steps:
Step 1: Create the Type Definition
Create src/types/[entityName].ts:
import type { Document, Types } from 'mongoose';
export type EntityName = {
/** Field description */
fieldName: string;
// ... other fields
};
export type IEntityName = EntityName &
Document & {
_id: Types.ObjectId;
};
Step 2: Update Types Index
Add to src/types/index.ts:
export * from './entityName';
Step 3: Create the Schema
Create src/schema/[entityName].ts:
import { Schema } from 'mongoose';
import type { IEntityName } from '~/types';
const entityNameSchema = new Schema<IEntityName>(
{
fieldName: { type: String, required: true },
// ... other fields
},
{ timestamps: true }
);
export default entityNameSchema;
Step 4: Create the Model Factory
Create src/models/[entityName].ts:
import entityNameSchema from '~/schema/entityName';
import type * as t from '~/types';
export function createEntityNameModel(mongoose: typeof import('mongoose')) {
return (
mongoose.models.EntityName ||
mongoose.model<t.IEntityName>('EntityName', entityNameSchema)
);
}
Step 5: Update Models Index
Add to src/models/index.ts:
- Import the factory function:
import { createEntityNameModel } from './entityName';
- Add to the return object in
createModels():
EntityName: createEntityNameModel(mongoose),
Step 6: Create Database Methods
Create src/methods/[entityName].ts:
import type { Model, Types } from 'mongoose';
import type { IEntityName } from '~/types';
export function createEntityNameMethods(mongoose: typeof import('mongoose')) {
async function findEntityById(id: string | Types.ObjectId): Promise<IEntityName | null> {
const EntityName = mongoose.models.EntityName as Model<IEntityName>;
return await EntityName.findById(id).lean();
}
// ... other methods
return {
findEntityById,
// ... other methods
};
}
export type EntityNameMethods = ReturnType<typeof createEntityNameMethods>;
Step 7: Update Methods Index
Add to src/methods/index.ts:
- Import the methods:
import { createEntityNameMethods, type EntityNameMethods } from './entityName';
- Add to the return object in
createMethods():
...createEntityNameMethods(mongoose),
- Add to the
AllMethodstype:
export type AllMethods = UserMethods &
// ... other methods
EntityNameMethods;
📝 Best Practices
- Consistent Naming: Use lowercase for filenames, PascalCase for types/interfaces
- Type Safety: Always use TypeScript types, avoid
any - JSDoc Comments: Document complex fields and methods
- Indexes: Define database indexes in schema files for query performance
- Validation: Use Mongoose schema validation for data integrity
- Lean Queries: Use
.lean()for read operations when you don't need Mongoose document methods
🔧 Common Patterns
Enums and Constants
Place shared enums in src/common/:
// src/common/permissions.ts
export enum PermissionBits {
VIEW = 1,
EDIT = 2,
DELETE = 4,
SHARE = 8,
}
Compound Indexes
For complex queries, add compound indexes:
schema.index({ field1: 1, field2: 1 });
schema.index(
{ uniqueField: 1 },
{
unique: true,
partialFilterExpression: { uniqueField: { $exists: true } }
}
);
Virtual Properties
Add computed properties using virtuals:
schema.virtual('fullName').get(function() {
return `${this.firstName} ${this.lastName}`;
});
🧪 Testing
When adding new entities, ensure:
- Types compile without errors
- Models can be created successfully
- Methods handle edge cases (null checks, validation)
- Indexes are properly defined for query patterns