{"id":11490,"library":"one-framework","title":"One Framework","description":"One Framework, currently at version 1.4.6, is a structured web application framework built upon RxJS, Lodash, and React. It provides an opinionated architecture for managing application state through reactive `Model` and `Collection` classes, designed to seamlessly integrate with RESTful JSON APIs and, with future updates, WebSockets. Models and collections leverage RxJS observables (specifically Subjects), allowing any data changes to automatically propagate to subscribed React components, thereby keeping the view synchronized with the underlying state. The framework differentiates itself by tightly coupling these popular libraries into a cohesive, reactive data management layer, offering a clear pattern for data persistence, validation, and real-time updates within a client-side application. While the exact release cadence is not explicitly stated, the version number suggests active, ongoing development.","status":"active","version":"1.4.6","language":"javascript","source_language":"en","source_url":"https://github.com/feliperohdee/one","tags":["javascript","typescript"],"install":[{"cmd":"npm install one-framework","lang":"bash","label":"npm"},{"cmd":"yarn add one-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add one-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core reactive programming paradigm for models, collections, and change streams.","package":"rxjs","optional":false},{"reason":"Intended for building UI components that react to model and collection changes.","package":"react","optional":false},{"reason":"Provides utility functions used internally for data manipulation (e.g., get, has, pick, omit).","package":"lodash","optional":false}],"imports":[{"note":"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.","wrong":"const Model = require('one-framework');","symbol":"Model","correct":"import { Model } from 'one-framework';"},{"note":"Classes like `Collection` are named exports, not default exports.","wrong":"import Collection from 'one-framework';","symbol":"Collection","correct":"import { Collection } from 'one-framework';"},{"note":"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.","wrong":"import { ISetOptions } from 'one-framework';","symbol":"ISetOptions","correct":"import type { ISetOptions } from 'one-framework';"}],"quickstart":{"code":"import { Model } from 'one-framework';\nimport { Subject } from 'rxjs';\n\ninterface IUserAttributes {\n  id?: string;\n  name: string;\n  email: string;\n  isActive?: boolean;\n}\n\nclass User extends Model<IUserAttributes> {\n  resource = '/users';\n  defaults = { isActive: true };\n  idAttribute = 'id';\n\n  validate(attributes: IUserAttributes) {\n    if (!attributes.name) return { name: 'Name is required.' };\n    if (!attributes.email || !attributes.email.includes('@')) return { email: 'Valid email is required.' };\n    return {};\n  }\n}\n\nconst user = new User({ name: 'John Doe', email: 'john.doe@example.com' });\n\n// Subscribe to changes on the model\nuser.updateStream.subscribe(change => {\n  console.log('Model changed:', change.type, change.payload);\n  console.log('Current user state:', user.toJSON());\n});\n\nconsole.log('Initial user:', user.toJSON());\n\n// Set properties, triggering an update\nuser.set({ isActive: false });\nuser.set({ name: 'Jane Doe', id: 'uuid-123' });\nuser.unset('email');\n\n// Attempt to save (requires a mock or actual backend)\n// user.save().subscribe({\n//   next: (response) => console.log('User saved:', response),\n//   error: (err) => console.error('Save error:', err)\n// });","lang":"typescript","description":"This quickstart demonstrates creating a reactive `Model`, defining its schema and validation, subscribing to its `updateStream` for real-time changes, and modifying its properties."},"warnings":[{"fix":"Do not attempt to set or modify `model.cid`. Rely on the framework to manage this property automatically.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Familiarize yourself with RxJS fundamentals. Ensure proper subscription management (e.g., unsubscribing to prevent memory leaks) and error handling within your observable chains.","message":"One 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Monitor 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.","message":"The 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.","severity":"breaking","affected_versions":"future major versions"},{"fix":"Always 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.","message":"One 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { Model } from 'one-framework';` (or your derived class) and that your build setup correctly handles ES Modules.","cause":"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.","error":"TypeError: Model is not a constructor"},{"fix":"Verify 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.","cause":"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.","error":"Cannot read properties of undefined (reading 'subscribe')"},{"fix":"Ensure 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.","cause":"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.","error":"Error: A model must have an 'id' property or an 'idAttribute' defined."},{"fix":"Check 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.","cause":"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.","error":"Unhandled Rejection (TypeError): Failed to fetch"}],"ecosystem":"npm"}