Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Model
✓ import { Model } from 'one-framework';
✗ const Model = require('one-framework');
One Framework is designed for modern JavaScript environments and primarily uses ES Modules. CommonJS `require` is not supported for its core classes without a transpiler setup.
Collection
✓ import { Collection } from 'one-framework';
✗ import Collection from 'one-framework';
Classes like `Collection` are named exports, not default exports.
ISetOptions
✓ import type { ISetOptions } from 'one-framework';
✗ import { ISetOptions } from 'one-framework';
For importing interfaces or types in TypeScript, it's a good practice to use `import type` to indicate it's purely a type import, which can be optimized during compilation.
This quickstart demonstrates creating a reactive `Model`, defining its schema and validation, subscribing to its `updateStream` for real-time changes, and modifying its properties.
import { Model } from 'one-framework';
import { Subject } from 'rxjs';
interface IUserAttributes {
id?: string;
name: string;
email: string;
isActive?: boolean;
}
class User extends Model<IUserAttributes> {
resource = '/users';
defaults = { isActive: true };
idAttribute = 'id';
validate(attributes: IUserAttributes) {
if (!attributes.name) return { name: 'Name is required.' };
if (!attributes.email || !attributes.email.includes('@')) return { email: 'Valid email is required.' };
return {};
}
}
const user = new User({ name: 'John Doe', email: 'john.doe@example.com' });
// Subscribe to changes on the model
user.updateStream.subscribe(change => {
console.log('Model changed:', change.type, change.payload);
console.log('Current user state:', user.toJSON());
});
console.log('Initial user:', user.toJSON());
// Set properties, triggering an update
user.set({ isActive: false });
user.set({ name: 'Jane Doe', id: 'uuid-123' });
user.unset('email');
// Attempt to save (requires a mock or actual backend)
// user.save().subscribe({
// next: (response) => console.log('User saved:', response),
// error: (err) => console.error('Save error:', err)
// });
Debug
Known issues
gotchaThe `cid` property is an internal unique identifier automatically attributed to each model instance. It is highly recommended to never override or manually manipulate this property, as it can lead to unpredictable behavior and state management issues within the framework.fixDo not attempt to set or modify `model.cid`. Rely on the framework to manage this property automatically.
affects: >=1.0.0
gotchaOne Framework relies heavily on RxJS for its reactive data streams (`updateStream`, `fetch`, `save`). Developers must have a good understanding of RxJS Observables, Subjects, and operators to effectively use and troubleshoot the framework, especially concerning subscriptions and error handling.fixFamiliarize yourself with RxJS fundamentals. Ensure proper subscription management (e.g., unsubscribing to prevent memory leaks) and error handling within your observable chains.
affects: >=1.0.0
breakingThe framework's current primary sync mechanism is RESTful JSON. The README indicates 'Websockets soon', implying a potential future shift or addition to the primary communication protocol. This could introduce significant changes to the `Sync` API or require different patterns for real-time updates.fixMonitor future release notes for major versions. Be prepared for potential refactoring of data synchronization logic if a WebSocket-based sync becomes the default or a primary alternative.
affects: future major versions
gotchaOne Framework is opinionated and integrates specific versions of RxJS, Lodash, and React. While not always explicit, upgrading any of these underlying libraries independently to new major versions might lead to compatibility issues or unexpected behavior within the framework.fixAlways check the `one-framework` peer dependencies or tested versions when upgrading RxJS, Lodash, or React. Consider upgrading `one-framework` itself before or concurrently with its core dependencies.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Model is not a constructor
Attempting to instantiate `Model` or a derived class using `new` without correctly importing it as a named export, or using CommonJS `require` in an ESM context.
fixEnsure you are using `import { Model } from 'one-framework';` (or your derived class) and that your build setup correctly handles ES Modules. Cannot read properties of undefined (reading 'subscribe')
This error typically occurs when trying to call `.subscribe()` on a variable that is `undefined`, often because an RxJS `Subject` (like `updateStream`) or an Observable method (like `fetch()`) was not properly initialized, or the return value of an async operation was not an Observable.
fixVerify that the model or collection instance is correctly initialized and that `updateStream` (or the Observable-returning method) is accessible. Ensure methods like `fetch()` or `save()` return an actual Observable before subscribing.
Error: A model must have an 'id' property or an 'idAttribute' defined.
When attempting to save or persist a model that is missing a unique identifier, or its `idAttribute` property is not correctly configured to point to an existing attribute.
fixEnsure your `Model` subclass defines an `idAttribute` property (e.g., `idAttribute = 'uuid';`) and that the model instance has a property matching this `idAttribute`'s name, or a default `id` property, before calling `save()` or `fetch()` for a specific instance.
Unhandled Rejection (TypeError): Failed to fetch
This error occurs when a `save()`, `fetch()`, `patch()`, or `delete()` operation attempts to communicate with a backend API but encounters a network error, a cross-origin issue, or the specified URL is incorrect/unreachable.
fixCheck your `resource` property on the Model/Collection. Ensure your API endpoint is running and accessible. Verify CORS policies if running client and server on different origins. Wrap network calls in a `try/catch` or handle errors in the `.subscribe()` method's error callback.
Audit
Dependencies
rxjsrequiredCore reactive programming paradigm for models, collections, and change streams.
reactrequiredIntended for building UI components that react to model and collection changes.
lodashrequiredProvides utility functions used internally for data manipulation (e.g., get, has, pick, omit).