Can-Local-Store

Common errors

• DOMException: QuotaExceededError: The quota has been exceeded.

  cause Attempting to write more data to localStorage than the browser's allocated limit (typically 5-10 MB per origin) allows.
  fix Reduce the amount of data being stored, implement a caching strategy to only store essential data, or migrate to a different storage mechanism like IndexedDB for larger datasets. Ensure `localStorage.removeItem()` or `localStorage.clear()` is used for cleanup when data is no longer needed.

• TypeError: Converting circular structure to JSON

  cause `can-local-store` uses `JSON.stringify` internally, which cannot handle objects with circular references (where an object directly or indirectly refers back to itself).
  fix Before saving, ensure that any data passed to `can-local-store` (via `Map` or `List` instances) does not contain circular references. Manually transform the data to a non-circular structure if necessary.

• Property 'save' does not exist on type 'Map<T>'

  cause This usually indicates an issue with how the CanJS `Map` is defined or how `can-local-store/map` is integrated, possibly due to incorrect peer dependency versions or an outdated CanJS setup.
  fix Verify that `can-define` and other peer dependencies are installed and compatible with `can-local-store@1.0.1`. Ensure the `Map` is correctly extended with `can-local-store/map` and that the instance methods like `save()` are available on the created model instance.

Warnings

• breaking The package is considered abandoned, with its last release in October 2017. It is unlikely to receive updates for newer browser features, JavaScript standards, or security patches, and may have compatibility issues with modern CanJS versions (beyond those specified in its peer dependencies) or other contemporary libraries.
  Fix: Consider migrating to a more actively maintained client-side storage solution or a direct `localStorage` wrapper if starting a new project or updating an existing one.
• gotcha `localStorage` has a limited storage capacity (typically 5-10 MB per origin). Attempting to store too much data will result in a `QuotaExceededError` or data loss, without graceful degradation unless explicitly handled.
  Fix: Implement robust error handling around `localStorage` operations and consider alternative storage solutions (e.g., IndexedDB) for larger datasets. Monitor storage usage and prune old data.
• gotcha `localStorage` operations are synchronous and can block the main thread. Storing or retrieving large amounts of data can lead to UI freezes and a poor user experience, especially on slower devices.
  Fix: For performance-critical applications or large data sets, use asynchronous storage solutions like IndexedDB or a web worker to offload synchronous `localStorage` operations.
• gotcha Data stored in `localStorage` is not secure and can be accessed or modified by any JavaScript code running on the same origin (e.g., via Cross-Site Scripting). Sensitive user information, authentication tokens, or highly confidential data should never be stored here.
  Fix: Avoid storing sensitive information. For secure client-side storage, consider using HTTP-only cookies for authentication tokens or server-side storage for critical data.
• gotcha can-local-store automatically serializes data using `JSON.stringify` and deserializes using `JSON.parse`. This means only JSON-serializable data types (strings, numbers, booleans, null, arrays, plain objects) can be reliably stored. Custom classes, Dates, RegExps, or functions will lose their type or information upon serialization.
  Fix: Ensure all data intended for storage is JSON-serializable. Manually serialize/deserialize complex types to and from their JSON-compatible representations before interacting with the store.

Install

• npm install can-local-store npm
• yarn add can-local-store yarn
• pnpm add can-local-store pnpm

Imports

• Map
  wrong:

  import { Map } from 'can-local-store'; // Incorrect named import from root
  import Map from 'can-local-store'; // Root default import usually refers to the main 'Map' store, but subpath is clearer

  correct:

  import Map from 'can-local-store/map';

  Imports a `can/Map` extended with localStorage persistence. This is the primary way to define models.
• List
  wrong:

  import { List } from 'can-local-store'; // Incorrect named import from root

  correct:

  import List from 'can-local-store/list';

  Imports a `can/List` extended with localStorage persistence. Used for collections of models.
• localStore
  wrong:

  const localStore = require('can-local-store');

  correct:

  import localStore from 'can-local-store'; // Or import Store from 'can-local-store';

  The root import often re-exports the `Map` variant or a factory function. The documentation primarily guides towards subpath imports for clarity. The d.ts indicates the default export is `can-local-store/map`.

Quickstart

Demonstrates defining a CanJS Map-based model with `can-local-store`, then performing CRUD (Create, Read, Update, Delete) operations that persist data in the browser's `localStorage`.

import Map from 'can-local-store/map';

// Define a Todo model that uses can-local-store/map
interface TodoAttributes {
  id?: number;
  name: string;
  completed: boolean;
}

const Todo = Map.extend<TodoAttributes>('todo', {
  // `todo` is the localStorage key for this model's data
  seal: false, // Recommended for can-define-stream compatibility
  init: function(this: any) {
    if (!this.id) {
      // Simple ID generation for example purposes
      this.id = Date.now();
    }
  }
});

async function runExample() {
  console.log('--- can-local-store example ---');

  // Create a new todo item
  const newTodo = new Todo({ name: 'Learn can-local-store', completed: false });
  await newTodo.save(); // Saves to localStorage under the key 'todo'
  console.log('Created todo:', newTodo.serialize());
  console.log('localStorage content (key "todo"):', localStorage.getItem('todo'));

  // Find all todos (loads from localStorage)
  const todos = await Todo.findAll({});
  console.log('All todos after creation:', todos.serialize());

  // Update an existing todo
  const firstTodo = todos.get(0);
  if (firstTodo) {
    firstTodo.completed = true;
    await firstTodo.save(); // Updates in localStorage
    console.log('Updated todo:', firstTodo.serialize());
    console.log('localStorage content (key "todo"):', localStorage.getItem('todo'));
  }

  // Find a specific todo by ID
  const foundTodo = await Todo.findOne({ id: newTodo.id });
  console.log('Found todo by ID:', foundTodo?.serialize());

  // Delete a todo
  if (foundTodo) {
    await foundTodo.destroy(); // Removes from localStorage
    console.log('Deleted todo:', foundTodo.serialize());
    console.log('localStorage content (key "todo"):', localStorage.getItem('todo'));
  }

  // Verify deletion by fetching all remaining todos
  const remainingTodos = await Todo.findAll({});
  console.log('Remaining todos:', remainingTodos.serialize());

  // Clean up localStorage completely for this example
  localStorage.removeItem('todo');
  console.log('localStorage "todo" key cleared.');
}

runExample().catch(console.error);