One Framework

Common errors

• TypeError: Model is not a constructor

  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.
  fix Ensure 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')

  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.
  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.

• Error: A model must have an 'id' property or an 'idAttribute' defined.

  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.
  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.

• Unhandled Rejection (TypeError): Failed to fetch

  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.
  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.

Warnings

• gotcha 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.
  Fix: Do not attempt to set or modify `model.cid`. Rely on the framework to manage this property automatically.
• gotcha 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.
  Fix: Familiarize yourself with RxJS fundamentals. Ensure proper subscription management (e.g., unsubscribing to prevent memory leaks) and error handling within your observable chains.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install one-framework npm
• yarn add one-framework yarn
• pnpm add one-framework pnpm

Imports

• Model
  wrong:

  const Model = require('one-framework');

  correct:

  import { Model } from '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
  wrong:

  import Collection from 'one-framework';

  correct:

  import { Collection } from 'one-framework';

  Classes like `Collection` are named exports, not default exports.
• ISetOptions
  wrong:

  import { ISetOptions } from 'one-framework';

  correct:

  import type { 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.

Quickstart

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)
// });