Dart FSRS

https://pub.dev/documentation/fsrs/latest
Admin
Dart FSRS is a Dart package that implements the Free Spaced Repetition Scheduler algorithm, enabling...
Tokens:18,903
Snippets:136
Trust Score:9.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Quickstart

Source: https://pub.dev/documentation/fsrs/latest/index.html

A quick guide to get started with the FSRS scheduler in Dart.

```APIDOC
## Quickstart

Import and initialize the FSRS scheduler
```dart
import 'package:fsrs/fsrs.dart';

var scheduler = Scheduler();
```

Create a new Card object
```dart
// note: all new cards are 'due' immediately upon creation
final card = Card(cardId: 1);
// alternatively, you can let fsrs generate a unique ID for you
final card = await Card.create();
```

Choose a rating and review the card with the scheduler
```dart
// Rating.Again (==1) forgot the card
// Rating.Hard (==2) remembered the card with serious difficulty
// Rating.Good (==3) remembered the card after a hesitation
// Rating.Easy (==4) remembered the card easily

final rating = Rating.good;

final (:card, :reviewLog) = scheduler.reviewCard(card, rating);

print("Card rated ${reviewLog.rating} at ${reviewLog.reviewDateTime}");
// > Card rated 3 at 2024-11-30 17:46:58.856497Z
```

See when the card is due next
```dart
final due = card.due;

// how much time between when the card is due and now
final timeDelta = due.difference(DateTime.now());

print("Card due on $due");
print("Card due in ${timeDelta.inSeconds} seconds");

// > Card due on 2024-12-01 17:46:58.856497Z
// > Card due in 599 seconds
```
```

--------------------------------

### Installation

Source: https://pub.dev/documentation/fsrs/latest/index.html

Instructions on how to add the fsrs package to your Dart project.

```APIDOC
## Installation

Add the package to your `pubspec.yaml`:
```yaml
dependencies:
  fsrs: ^2.0.0
```

and then run:
```bash
dart pub get
```

Or just install it with dart cli:
```bash
dart pub add fsrs
```
```

--------------------------------

### Install Dart-FSRS Package

Source: https://pub.dev/documentation/fsrs/latest/index.html

Instructions for adding the FSRS dependency to a Dart project via pubspec.yaml or the command line.

```yaml
dependencies:
  fsrs: ^2.0.0
```

```bash
dart pub get
# Or
dart pub add fsrs
```

--------------------------------

### GET /properties/hashCode

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/hashCode.html

Documentation for the hashCode property implementation and its role in object equality.

```APIDOC
## GET /properties/hashCode

### Description
Returns the hash code for the object. The hash code is a single integer representing the state of the object, ensuring compatibility with hash-based collections like Set and Map.

### Method
GET

### Endpoint
/properties/hashCode

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **hashCode** (int) - The integer representation of the object state.

#### Response Example
{
  "hashCode": 123456789
}

### Implementation Details
```dart
@override
int get hashCode {
  return Object.hash(
    Object.hashAll(parameters),
    desiredRetention,
    Object.hashAll(learningSteps),
    Object.hashAll(relearningSteps),
    maximumInterval,
    enableFuzzing,
  );
}
```
```

--------------------------------

### GET /fsrs/parameters

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/parameters.html

Retrieves the current model weights used by the FSRS scheduler.

```APIDOC
## GET /fsrs/parameters

### Description
Returns the current list of model weights (parameters) used by the FSRS scheduler to calculate intervals and stability.

### Method
GET

### Endpoint
/fsrs/parameters

### Parameters
None

### Request Example
GET /fsrs/parameters

### Response
#### Success Response (200)
- **parameters** (List<double>) - The model weights of the FSRS scheduler.

#### Response Example
{
  "parameters": [0.4, 0.6, 2.4, 5.8, 4.93, 0.94, 0.86, 0.01, 1.49, 0.14, 0.94, 2.18, 0.05, 0.34, 1.26, 0.29, 2.61]
}
```

--------------------------------

### GET /card/due

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/due.html

Accessing the due property to determine when a card is scheduled for its next review.

```APIDOC
## GET /card/due

### Description
Retrieves the scheduled date and time for the next card review.

### Method
GET

### Endpoint
/card/due

### Parameters
None

### Request Example
GET /card/due

### Response
#### Success Response (200)
- **due** (DateTime) - The ISO 8601 formatted string representing the next review time.

#### Response Example
{
  "due": "2023-10-27T10:00:00Z"
}
```

--------------------------------

### GET /config/maximumInterval

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/maximumInterval.html

Retrieves or defines the maximum number of days a Review-state card can be scheduled into the future.

```APIDOC
## GET /config/maximumInterval

### Description
Returns the maximum interval value configured for the FSRS scheduling engine. This value determines the cap on how far into the future a card can be scheduled.

### Method
GET

### Endpoint
/config/maximumInterval

### Parameters
None

### Request Example
GET /config/maximumInterval

### Response
#### Success Response (200)
- **maximumInterval** (int) - The maximum number of days a Review-state card can be scheduled.

#### Response Example
{
  "maximumInterval": 36500
}
```

--------------------------------

### GET /card/cardId

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/cardId.html

Retrieves the unique identifier for a card object.

```APIDOC
## GET /card/cardId

### Description
Returns the unique integer identifier for a card. This value defaults to the epoch milliseconds of the card's creation time.

### Method
GET

### Endpoint
/card/cardId

### Parameters
None

### Request Example
GET /card/cardId

### Response
#### Success Response (200)
- **cardId** (int) - The unique identifier of the card.

#### Response Example
{
  "cardId": 1672531200000
}
```

--------------------------------

### GET /properties/difficulty

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/difficulty.html

Retrieves or updates the difficulty property, which is a double value representing the memory load of a card.

```APIDOC
## GET /properties/difficulty

### Description
Retrieves the current difficulty value used for FSRS scheduling calculations.

### Method
GET

### Endpoint
/properties/difficulty

### Parameters
None

### Request Example
GET /properties/difficulty

### Response
#### Success Response (200)
- **difficulty** (double) - The current difficulty value.

#### Response Example
{
  "difficulty": 0.5
}
```

--------------------------------

### Fuzz Ranges Constant Implementation (Dart)

Source: https://pub.dev/documentation/fsrs/latest/fsrs/fuzzRanges-constant.html

This snippet shows the implementation of the fuzzRanges constant in Dart. It defines a list of maps, where each map specifies a 'start' and 'end' value for a range, along with a 'factor' to be applied within that range. The last range extends to infinity.

```dart
List<Map<String, double>> const fuzzRanges = [
  {
    'start': 2.5,
    'end': 7.0,
    'factor': 0.15,
  },
  {
    'start': 7.0,
    'end': 20.0,
    'factor': 0.1,
  },
  {
    'start': 20.0,
    'end': double.infinity,
    'factor': 0.05,
  },
];
```

--------------------------------

### Initialize Scheduler and Create Cards

Source: https://pub.dev/documentation/fsrs/latest/index.html

Demonstrates how to import the library, initialize the FSRS scheduler, and instantiate new cards for the system.

```dart
import 'package:fsrs/fsrs.dart';

var scheduler = Scheduler();

// Create a new card
final card = Card(cardId: 1);
// Or generate a unique ID
final cardAsync = await Card.create();
```

--------------------------------

### Serialization

Source: https://pub.dev/documentation/fsrs/latest/index.html

Demonstrates how to serialize Scheduler, Card, and ReviewLog objects to Map format for storage and deserialize them back into objects.

```APIDOC
## Serialization

`Scheduler`, `Card` and `ReviewLog` classes are all JSON-serializable via their `toMap` and `fromMap` methods for easy database storage:

```dart
// serialize before storage
final schedulerDict = scheduler.toMap();
final cardDict = card.toMap();
final reviewLogDict = reviewLog.toMap();

// deserialize from dict
final newScheduler = Scheduler.fromMap(schedulerDict);
final newCard = Card.fromMap(cardDict);
final newReviewLog = ReviewLog.fromMap(reviewLogDict);
```
```

--------------------------------

### Static Method: Card.create

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/create.html

Initializes a new Card object with FSRS scheduling parameters.

```APIDOC
## POST Card.create

### Description
Creates a new flashcard instance with an automatically generated unique ID based on the current timestamp.

### Method
Static Method (Dart)

### Parameters
#### Optional Parameters
- **state** (State) - Optional - The current learning state (default: State.learning)
- **step** (int) - Optional - The current step in the learning process
- **stability** (double) - Optional - The stability of the card
- **difficulty** (double) - Optional - The difficulty rating of the card
- **due** (DateTime) - Optional - The scheduled due date
- **lastReview** (DateTime) - Optional - The timestamp of the last review

### Request Example
Card.create(state: State.learning, stability: 1.0)

### Response
#### Success Response
- **Card** (Object) - Returns a new Card instance with a unique cardId generated from the current epoch milliseconds.

#### Response Example
{
  "cardId": 1715678901234,
  "state": "learning",
  "stability": 1.0,
  "difficulty": null,
  "due": null,
  "lastReview": null
}
```

--------------------------------

### Usage - Custom Parameters

Source: https://pub.dev/documentation/fsrs/latest/index.html

How to initialize the FSRS scheduler with custom parameters for fine-grained control.

```APIDOC
## Usage

### Custom parameters
You can initialize the FSRS scheduler with your own custom parameters.
```dart
// note: the following arguments are also the defaults
scheduler = Scheduler(
  parameters: [
    0.2172,
    1.1771,
    3.2602,
    16.1507,
    7.0114,
    0.57,
    2.0966,
    0.0069,
    1.5261,
    0.112,
    1.0178,
    1.849,
    0.1133,
    0.3127,
    2.2934,
    0.2191,
    3.0004,
    0.7536,
    0.3332,
    0.1437,
    0.2,
  ],
  desiredRetention: 0.9,
  learningSteps: [
    Duration(minutes: 1),
    Duration(minutes: 10),
  ],
  relearningSteps: [
    Duration(minutes: 10),
  ],
  maximumInterval: 36500,
  enableFuzzing: true,
);

```

#### Explanation of parameters
`parameters` are a set of 21 model weights that affect how the FSRS scheduler will schedule future reviews. If you're not familiar with optimizing FSRS, it is best not to modify these default values.
`desired_retention` is a value between 0 and 1 that sets the desired minimum retention rate for cards when scheduled with the scheduler. For example, with the default value of `desired_retention=0.9`, a card will be scheduled at a time in the future when the predicted probability of the user correctly recalling that card falls to 90%. A higher `desired_retention` rate will lead to more reviews and a lower rate will lead to fewer reviews.
`learning_steps` are custom time intervals that schedule new cards in the Learning state. By default, cards in the Learning state have short intervals of 1 minute then 10 minutes. You can also disable `learning_steps` with `Scheduler(learning_steps=())`
`relearning_steps` are analogous to `learning_steps` except they apply to cards in the Relearning state. Cards transition to the Relearning state if they were previously in the Review state, then were rated Again - this is also known as a 'lapse'. If you specify `Scheduler(relearning_steps=())`, cards in the Review state, when lapsed, will not move to the Relearning state, but instead stay in the Review state.
`maximum_interval` sets the cap for the maximum days into the future the scheduler is capable of scheduling cards. For example, if you never want the scheduler to schedule a card more than one year into the future, you'd set `Scheduler(maximum_interval=365)`.
`enable_fuzzing`, if set to True, will apply a small amount of random 'fuzz' to calculated intervals. For example, a card that would've been due in 50 days, after fuzzing, might be due in 49, or 51 days.
```

--------------------------------

### Initialize ReviewLog instance

Source: https://pub.dev/documentation/fsrs/latest/fsrs/ReviewLog/ReviewLog.html

Constructs a new ReviewLog object. It requires the cardId, rating, and reviewDateTime, while allowing an optional reviewDuration to track how long the review took.

```dart
const ReviewLog({
  required this.cardId,
  required this.rating,
  required this.reviewDateTime,
  this.reviewDuration,
});
```

--------------------------------

### License and More Info

Source: https://pub.dev/documentation/fsrs/latest/index.html

Provides information about the project's license and origin.

```APIDOC
## License

Distributed under the MIT License. See `LICENSE` for more information.

## More Info:

Port from open-spaced-repetition/py-fsrs@6fd0857

## Online development

idx.google.com/import

## Libraries 

fsrs 
    This module defines each of the classes used in the fsrs package. 
```

--------------------------------

### Method: toString()

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/toString.html

Provides a string representation of the Scheduler object, including its parameters, retention settings, and learning steps.

```APIDOC
## toString()

### Description
Returns a string representation of the Scheduler object. This is primarily used for debugging and logging purposes to inspect the current state of the scheduler configuration.

### Method
N/A (Class Method)

### Parameters
None

### Implementation
```dart
@override
String toString() {
  return 'Scheduler(' 
      'parameters: $parameters, ' 
      'desiredRetention: $desiredRetention, ' 
      'learningSteps: $learningSteps, ' 
      'relearningSteps: $relearningSteps, ' 
      'maximumInterval: $maximumInterval, ' 
      'enableFuzzing: $enableFuzzing)';
}
```

### Response
- **Type**: String
- **Description**: A formatted string containing the internal state of the Scheduler object.
```

--------------------------------

### Static Card Creation Methods

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card-class.html

Methods for creating Card objects, including from a map or with default values.

```APIDOC
## Static Card Methods

### `create`

```dart
static Future<Card> create({
  State state = State.learning,
  int? step,
  double? stability,
  double? difficulty,
  DateTime? due,
  DateTime? lastReview,
})
```

**Description**: Creates a new Card instance with optional initial parameters.

### `fromMap`

```dart
static Card fromMap(Map<String, dynamic> sourceMap)
```

**Description**: Creates a Card instance from a Map representation, typically from JSON data.
```

--------------------------------

### Scheduler Constructor

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/Scheduler.html

Initializes the FSRS scheduler with customizable parameters for card review and future scheduling based on the FSRS algorithm.

```APIDOC
## Scheduler Constructor

### Description
Initializes the FSRS scheduler with customizable parameters for card review and future scheduling based on the FSRS algorithm.

### Method
Constructor

### Endpoint
N/A (Dart Class Constructor)

### Parameters
#### Named Parameters
- **parameters** (List<double>) - Optional - Default: `defaultParameters` - The FSRS algorithm parameters.
- **desiredRetention** (double) - Optional - Default: `0.9` - The desired retention rate.
- **learningSteps** (List<Duration>) - Optional - Default: `[Duration(minutes: 1), Duration(minutes: 10)]` - Steps for learning new cards.
- **relearningSteps** (List<Duration>) - Optional - Default: `[Duration(minutes: 10)]` - Steps for relearning cards.
- **maximumInterval** (int) - Optional - Default: `36500` - The maximum interval in days for card reviews.
- **enableFuzzing** (bool) - Optional - Default: `true` - Enables fuzzing for review intervals.

### Request Example
```dart
Scheduler(
  parameters: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0, 2.1],
  desiredRetention: 0.85,
  learningSteps: const [Duration(minutes: 5), Duration(minutes: 15)],
  relearningSteps: const [Duration(hours: 1)],
  maximumInterval: 73000,
  enableFuzzing: false,
);
```

### Response
#### Success Response (Instance)
- **Scheduler Instance** - An instance of the Scheduler class configured with the provided parameters.

#### Response Example
```dart
// Returns a Scheduler instance
```
```

--------------------------------

### Review Cards and Calculate Due Dates

Source: https://pub.dev/documentation/fsrs/latest/index.html

Shows how to process a card review using a rating and retrieve the updated card status and next due date.

```dart
final rating = Rating.good;
final (:card, :reviewLog) = scheduler.reviewCard(card, rating);

print("Card rated ${reviewLog.rating} at ${reviewLog.reviewDateTime}");

final due = card.due;
final timeDelta = due.difference(DateTime.now());
print("Card due on $due");
```

--------------------------------

### Initialize FSRS Scheduler

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/Scheduler.html

Initializes the Scheduler instance with customizable FSRS parameters, retention targets, and learning steps. It validates the provided parameters and sets up internal decay and factor calculations for interval scheduling.

```dart
Scheduler({
  List<double> parameters = defaultParameters,
  this.desiredRetention = 0.9,
  this.learningSteps = const [
    Duration(minutes: 1),
    Duration(minutes: 10),
  ],
  this.relearningSteps = const [
    Duration(minutes: 10),
  ],
  this.maximumInterval = 36500,
  this.enableFuzzing = true,
}) : parameters = List<double>.from(parameters) {
  _validateParameters(this.parameters);

  _decay = -this.parameters[20];
  _factor = math.pow(0.9, 1 / _decay) - 1;

  _fuzzRandom = math.Random();
}
```

--------------------------------

### Create FSRS Card (Dart)

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/create.html

This static method creates a new FSRS Card object. It initializes the card with default learning states or provided parameters. A small delay is included to prevent potential ID collisions.

```dart
static Future<Card> create({
  State state = State.learning,
  int? step,
  double? stability,
  double? difficulty,
  DateTime? due,
  DateTime? lastReview,
}) async {
  // epoch milliseconds of when the card was created
  final cardId = DateTime.now().millisecondsSinceEpoch;

  // wait 1ms to prevent potential cardId collision on next Card creation
  await Future.delayed(const Duration(milliseconds: 1));

  return Card(
    cardId: cardId,
    state: state,
    step: step,
    stability: stability,
    difficulty: difficulty,
    due: due,
    lastReview: lastReview,
  );
}
```

--------------------------------

### Relearning Steps Property

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/relearningSteps.html

Defines the time intervals for scheduling cards in the Relearning state.

```APIDOC
## Relearning Steps Property

### Description
Small time intervals that schedule cards in the Relearning state.

### Type
List<Duration>

### Implementation
```dart
final List<Duration> relearningSteps;
```
```

--------------------------------

### Configure Custom FSRS Parameters

Source: https://pub.dev/documentation/fsrs/latest/index.html

Configures the scheduler with custom weights, retention goals, learning steps, and interval constraints.

```dart
scheduler = Scheduler(
  parameters: [0.2172, 1.1771, 3.2602, 16.1507, 7.0114, 0.57, 2.0966, 0.0069, 1.5261, 0.112, 1.0178, 1.849, 0.1133, 0.3127, 2.2934, 0.2191, 3.0004, 0.7536, 0.3332, 0.1437, 0.2],
  desiredRetention: 0.9,
  learningSteps: [Duration(minutes: 1), Duration(minutes: 10)],
  relearningSteps: [Duration(minutes: 10)],
  maximumInterval: 36500,
  enableFuzzing: true
);
```

--------------------------------

### static Scheduler fromMap

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/fromMap.html

Creates a new Scheduler instance from a provided Map object containing FSRS configuration parameters.

```APIDOC
## POST /scheduler/fromMap

### Description
Initializes a new Scheduler object using a map of configuration parameters, including retention rates, learning steps, and interval constraints.

### Method
POST

### Endpoint
/scheduler/fromMap

### Parameters
#### Request Body
- **parameters** (List<double>) - Required - List of FSRS algorithm parameters.
- **desiredRetention** (double) - Required - The target retention rate.
- **learningSteps** (List<int>) - Required - List of durations in seconds for learning steps.
- **relearningSteps** (List<int>) - Required - List of durations in seconds for relearning steps.
- **maximumInterval** (int) - Required - The maximum allowed interval.
- **enableFuzzing** (bool) - Required - Whether to enable fuzzing for scheduling.

### Request Example
{
  "parameters": [0.4, 0.6, 2.4, 5.8, 4.93, 0.94, 0.86, 0.01, 1.49, 0.11, 0.94, 2.18, 0.05, 0.34, 1.26, 0.29, 2.61],
  "desiredRetention": 0.9,
  "learningSteps": [60, 300],
  "relearningSteps": [60, 300],
  "maximumInterval": 36500,
  "enableFuzzing": true
}

### Response
#### Success Response (200)
- **Scheduler** (Object) - Returns an initialized Scheduler instance.

#### Response Example
{
  "status": "success",
  "message": "Scheduler initialized successfully"
}
```

--------------------------------

### ReviewLog Class Overview

Source: https://pub.dev/documentation/fsrs/latest/fsrs/ReviewLog-class.html

Provides an overview of the ReviewLog class and its purpose.

```APIDOC
## ReviewLog Class

Represents the log entry of a Card object that has been reviewed.

### Constructors

*   **ReviewLog**({required int cardId, required Rating rating, required DateTime reviewDateTime, int? reviewDuration})
    Represents the log entry of a Card object that has been reviewed.

### Properties

*   **cardId** → int
    The id of the card being reviewed.
*   **hashCode** → int
    The hash code for this object.
*   **rating** → Rating
    The rating given to the card during the review.
*   **reviewDateTime** → DateTime
    The date and time of the review.
*   **reviewDuration** → int?
    The number of milliseconds it took to review the card or null if unspecified.
*   **runtimeType** → Type
    A representation of the runtime type of the object.

### Methods

*   **noSuchMethod**(Invocation invocation) → dynamic
    Invoked when a nonexistent method or property is accessed.
*   **toMap**() → Map<String, dynamic>
    Returns a JSON-serializable Map representation of the ReviewLog object.
*   **toString**() → String
    A string representation of this object.

### Operators

*   **operator ==**(Object other) → bool
    The equality operator.

### Static Methods

*   **fromMap**(Map<String, dynamic> sourceMap) → ReviewLog
    Represents the log entry of a Card object that has been reviewed.
```

--------------------------------

### FSRS Scheduler Methods

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler-class.html

Includes methods for calculating card retrievability, reviewing cards with different ratings, converting the scheduler to a map for serialization, and handling non-existent method calls.

```dart
getCardRetrievability(Card card, {DateTime? currentDateTime}) → double
     Calculates a Card object's current retrievability for a given date and time.
```

```dart
noSuchMethod(Invocation invocation) → dynamic
     Invoked when a nonexistent method or property is accessed.
inherited
```

```dart
reviewCard(Card card, Rating rating, {DateTime? reviewDateTime, int? reviewDuration}) → ({Card card, ReviewLog reviewLog})
     Reviews a card with a given rating at a given time for a specified duration.
```

```dart
toMap() → Map<String, dynamic>
     Returns a JSON-serializable Map representation of the Scheduler object.
```

```dart
toString() → String
     A string representation of this object.
override
```

--------------------------------

### Static Method: fromMap

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/fromMap.html

Converts a Map object into a Card instance for the FSRS flashcard system.

```APIDOC
## POST /card/fromMap

### Description
Creates a new Card object by parsing a Map containing flashcard data attributes.

### Method
POST

### Endpoint
/card/fromMap

### Parameters
#### Request Body
- **sourceMap** (Map<String, dynamic>) - Required - A map containing keys: cardId, state, step, stability, difficulty, due, and lastReview.

### Request Example
{
  "cardId": 1,
  "state": 0,
  "due": "2023-10-27T10:00:00Z"
}

### Response
#### Success Response (200)
- **Card** (Object) - Returns a fully instantiated Card object.

#### Response Example
{
  "cardId": 1,
  "state": "New",
  "due": "2023-10-27T10:00:00.000Z"
}
```

--------------------------------

### State Property Implementation

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/state.html

This snippet shows the declaration of the 'state' property, which holds the current learning state of a card. It is typically implemented as a getter/setter pair to manage access to the state value.

```C++
State state;
```

--------------------------------

### ReviewLog Constructor

Source: https://pub.dev/documentation/fsrs/latest/fsrs/ReviewLog/ReviewLog.html

Defines the ReviewLog constructor, used to create log entries for reviewed cards. It includes required fields like cardId, rating, and reviewDateTime, along with an optional reviewDuration.

```APIDOC
## ReviewLog Constructor

### Description
Represents the log entry of a Card object that has been reviewed.

### Method
Constructor

### Endpoint
N/A (Class Constructor)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```dart
// Example of creating a ReviewLog object
const ReviewLog(
  cardId: 123,
  rating: Rating.good, // Assuming Rating is an enum
  reviewDateTime: DateTime.now(),
  reviewDuration: 60000, // in milliseconds
);
```

### Response
#### Success Response (200)
N/A (Constructor)

#### Response Example
```dart
// No direct response example for a constructor, but an instance is created.
```

## Implementation
```dart
const ReviewLog({
  required this.cardId,
  required this.rating,
  required this.reviewDateTime,
  this.reviewDuration,
});
```
```

--------------------------------

### Method: toMap()

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/toMap.html

Serializes the Card object into a Map for database persistence.

```APIDOC
## Method: toMap()

### Description
Converts the current Card instance into a Map<String, dynamic> object. This is primarily used for serializing the object state for storage in databases.

### Method
N/A (Internal Class Method)

### Parameters
None

### Returns
- **Map<String, dynamic>** - A dictionary containing the card's properties: cardId, state, step, stability, difficulty, due, and lastReview.

### Implementation Example
```dart
Map<String, dynamic> toMap() {
  return {
    'cardId': cardId,
    'state': state.value,
    'step': step,
    'stability': stability,
    'difficulty': difficulty,
    'due': due.toIso8601String(),
    'lastReview': lastReview?.toIso8601String(),
  };
}
```
```

--------------------------------

### FSRS Scheduler Constructor

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler-class.html

Initializes the FSRS scheduler with customizable parameters, desired retention, learning/relearning steps, maximum interval, and fuzzing option. Supports custom random number generation.

```dart
Scheduler({List<double> parameters = defaultParameters, double desiredRetention = 0.9, List<Duration> learningSteps = const [Duration(minutes: 1), Duration(minutes: 10)], List<Duration> relearningSteps = const [Duration(minutes: 10)], int maximumInterval = 36500, bool enableFuzzing = true})
     The FSRS scheduler.
```

```dart
Scheduler.customRandom(Random random, {List<double> parameters = defaultParameters, double desiredRetention = 0.9, List<Duration> learningSteps = const [Duration(minutes: 1), Duration(minutes: 10)], List<Duration> relearningSteps = const [Duration(minutes: 10)], int maximumInterval = 36500, bool enableFuzzing = true})
     The FSRS scheduler.
```

--------------------------------

### Step Property

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/step.html

Details the 'step' property for card learning states.

```APIDOC
## Step Property

### Description
The card's current learning or relearning step or null if the card is in the Review state.

### Implementation
```dart
int? step;
```
```

--------------------------------

### hashCode Property Overview

Source: https://pub.dev/documentation/fsrs/latest/fsrs/ReviewLog/hashCode.html

Provides a detailed explanation of the hashCode property, its contract with the operator ==, and its role in data structures.

```APIDOC
## hashCode Property

### Description
The `hashCode` property returns a single integer representing the state of an object that affects equality comparisons. It is crucial for objects used in hash-based data structures like `Set` and `Map`.

### Contract
- Objects that are equal according to `operator ==` must have the same `hashCode`.
- The `hashCode` should only change if the object's state changes in a way that affects equality.
- While not strictly required, frequent hash code collisions can reduce the efficiency of hash-based collections.

### Default Implementation
The default `hashCode` implementation in `Object` uses the object's identity. If `operator ==` is overridden to compare object state, `hashCode` must also be overridden to reflect that state.

### Implementation Example
```dart
@override
int get hashCode {
  return Object.hash(cardId, rating, reviewDateTime, reviewDuration);
}
```

### Related Concepts
- `operator ==`
- `Object.hash`
- Hash-based data structures (e.g., `HashSet`, `HashMap`)
```

--------------------------------

### Initialize Scheduler from Map

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/fromMap.html

This method converts a raw map into a fully initialized Scheduler object. It handles type casting for parameters, duration conversion for learning steps, and configuration of interval limits.

```dart
static Scheduler fromMap(Map<String, dynamic> sourceMap) {
  return Scheduler(
    parameters: List<double>.from(sourceMap['parameters']),
    desiredRetention: sourceMap['desiredRetention'] as double,
    learningSteps: (sourceMap['learningSteps'] as List)
        .map((step) => Duration(seconds: step as int))
        .toList(),
    relearningSteps: (sourceMap['relearningSteps'] as List)
        .map((step) => Duration(seconds: step as int))
        .toList(),
    maximumInterval: sourceMap['maximumInterval'] as int,
    enableFuzzing: sourceMap['enableFuzzing'] as bool,
  );
}
```

--------------------------------

### Create FSRS Scheduler with Custom Random Generator (Dart)

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/Scheduler.customRandom.html

This factory constructor `Scheduler.customRandom` creates an instance of the FSRS scheduler, allowing a specific `math.Random` object to be provided. This is particularly useful for reproducible testing scenarios where the randomness of the scheduling algorithm needs to be controlled. It accepts various parameters to configure the scheduler's behavior, including learning and relearning steps, desired retention, and maximum interval.

```dart
@visibleForTesting
factory Scheduler.customRandom(
  math.Random random, {
  List<double> parameters = defaultParameters,
  double desiredRetention = 0.9,
  List<Duration> learningSteps = const [
    Duration(minutes: 1),
    Duration(minutes: 10),
  ],
  List<Duration> relearningSteps = const [
    Duration(minutes: 10),
  ],
  int maximumInterval = 36500,
  bool enableFuzzing = true,
}) {
  final scheduler = Scheduler(
    parameters: parameters,
    desiredRetention: desiredRetention,
    learningSteps: learningSteps,
    relearningSteps: relearningSteps,
    maximumInterval: maximumInterval,
    enableFuzzing: enableFuzzing,
  );

  scheduler._fuzzRandom = random;

  return scheduler;
}
```

--------------------------------

### State Enum

Source: https://pub.dev/documentation/fsrs/latest/fsrs/State.html

Defines the possible learning states for a card, including learning, review, and relearning.

```APIDOC
## State Enum

### Description
Enum representing the learning state of a Card object.

### Values

- **learning**: Represents the state where a card is currently being learned. `const State(1)`
- **review**: Represents the state where a card is due for review. `const State(2)`
- **relearning**: Represents the state where a card is being relearned. `const State(3)`

### Properties

- **hashCode** (int) - The hash code for this object.
- **index** (int) - A numeric identifier for the enumerated value.
- **name** (String) - The name of the enum value.
- **runtimeType** (Type) - A representation of the runtime type of the object.
- **value** (int) - The integer value associated with the enum constant.

### Static Methods

- **fromValue**(int value) → State - Returns the State enum constant corresponding to the given integer value. Enum representing the learning state of a Card object.
```

--------------------------------

### hashCode Property Implementation

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/hashCode.html

Details on how the hashCode property is implemented to represent object state for equality comparisons.

```APIDOC
## GET hashCode

### Description
Returns a single integer representing the state of the object, used for hash-based data structures like Set and Map.

### Method
GET (Property Access)

### Endpoint
hashCode

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **hashCode** (int) - The calculated hash code based on cardId, state, step, stability, difficulty, due, and lastReview.

#### Response Example
{
  "hashCode": 123456789
}
```

--------------------------------

### Serialize and Deserialize FSRS Objects

Source: https://pub.dev/documentation/fsrs/latest/index.html

Demonstrates how to convert Scheduler, Card, and ReviewLog objects to and from JSON-compatible maps for database storage. These methods ensure that the state of the FSRS scheduler and card objects can be persisted and retrieved accurately.

```dart
// serialize before storage
final schedulerDict = scheduler.toMap();
final cardDict = card.toMap();
final reviewLogDict = reviewLog.toMap();

// deserialize from dict
final newScheduler = Scheduler.fromMap(schedulerDict);
final newCard = Card.fromMap(cardDict);
final newReviewLog = ReviewLog.fromMap(reviewLogDict);
```

--------------------------------

### FSRS Scheduler Static Methods

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler-class.html

Provides a static method to create a Scheduler instance from a map, typically used for deserialization.

```dart
fromMap(Map<String, dynamic> sourceMap) → Scheduler
     The FSRS scheduler.
```

--------------------------------

### State Property

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/state.html

This section describes the 'state' property, which is a getter/setter pair used to manage the card's current learning state.

```APIDOC
## State Property

### Description
The card's current learning state.

### Method
Getter/Setter Pair

### Endpoint
N/A (Local property)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **state** (State) - The current learning state of the card.

#### Response Example
```json
{
  "state": "learning"
}
```

## Implementation
```dart
State state;
```
```

--------------------------------

### Usage - Timezone and Retrievability

Source: https://pub.dev/documentation/fsrs/latest/index.html

Information on timezone handling and calculating card retrievability.

```APIDOC
### Timezone
**Dart-FSRS uses UTC only.**
You can still specify custom datetimes, but they must use the UTC timezone.

### Retrievability
You can calculate the current probability of correctly recalling a card (its 'retrievability') with
```dart
final retrievability = scheduler.getCardRetrievability(card);

print("There is a $retrievability probability that this card is remembered.");
// > There is a 0.94 probability that this card is remembered.
```
```

--------------------------------

### Implement Card Review Logic

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/reviewCard.html

The reviewCard method processes a card review, accepting card details, a rating, and optional review metadata like date and duration. It returns the updated card and a review log. Ensure reviewDateTime is in UTC to avoid ArgumentError.

```Dart
({Card card, ReviewLog reviewLog}) reviewCard(
  1. Card card,
  2. Rating rating, {
  3. DateTime? reviewDateTime,
  4. int? reviewDuration,

})
{
  // Implementation details for reviewing a card
  // ...
  // Returns a tuple of the updated card and its review log
  // Throws ArgumentError if reviewDateTime is not in UTC
  throw UnimplementedError();
}
```

--------------------------------

### Define Default Parameters List (Dart)

Source: https://pub.dev/documentation/fsrs/latest/fsrs/defaultParameters-constant.html

This snippet defines a top-level constant list named 'defaultParameters' containing double-precision floating-point numbers. These values are essential for initializing the FSRS algorithm with its default settings. No external dependencies are required for this definition.

```dart
List<double> const defaultParameters = [
  0.2172,
  1.1771,
  3.2602,
  16.1507,
  7.0114,
  0.57,
  2.0966,
  0.0069,
  1.5261,
  0.112,
  1.0178,
  1.849,
  0.1133,
  0.3127,
  2.2934,
  0.2191,
  3.0004,
  0.7536,
  0.3332,
  0.1437,
  0.2,
];
```

--------------------------------

### Dart Card Constructor for FSRS

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/Card.html

Defines the Card constructor for the FSRS system. It initializes card properties like ID, state, stability, and difficulty. It also handles the default step for learning cards.

```dart
Card({
  required this.cardId,
  this.state = State.learning,
  this.step,
  this.stability,
  this.difficulty,
  DateTime? due,
  this.lastReview,
}) : due = due ?? DateTime.now().toUtc() {
  if (state == State.learning && step == null) {
    step = 0;
  }
}
```

--------------------------------

### FSRS Scheduler Properties

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler-class.html

Provides access to the configuration and state of the FSRS scheduler, including desired retention, fuzzing status, learning/relearning steps, maximum interval, and model parameters.

```dart
desiredRetention → double
     The desired retention rate of cards scheduled with the scheduler.
final
```

```dart
enableFuzzing → bool
     Whether to apply a small amount of random 'fuzz' to calculated intervals.
final
```

```dart
hashCode → int
     The hash code for this object.
no setteroverride
```

```dart
learningSteps → List<Duration>
     Small time intervals that schedule cards in the Learning state.
final
```

```dart
maximumInterval → int
     The maximum number of days a Review-state card can be scheduled into the future.
final
```

```dart
parameters → List<double>
     The model weights of the FSRS scheduler.
final
```

```dart
relearningSteps → List<Duration>
     Small time intervals that schedule cards in the Relearning state.
final
```

```dart
runtimeType → Type
     A representation of the runtime type of the object.
no setterinherited
```

--------------------------------

### Create Card from Map (Dart)

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/fromMap.html

Implements a static method to create a Card object from a Map. It parses various fields including IDs, states, dates, and numerical values from the source map. Handles optional fields like lastReview.

```Dart
static Card fromMap(Map<String, dynamic> sourceMap) {
  return Card(
    cardId: sourceMap['cardId'] as int,
    state: State.fromValue(sourceMap['state'] as int),
    step: sourceMap['step'] as int?,
    stability: sourceMap['stability'] as double?,
    difficulty: sourceMap['difficulty'] as double?,
    due: DateTime.parse(sourceMap['due'] as String),
    lastReview: sourceMap['lastReview'] != null
        ? DateTime.parse(sourceMap['lastReview'] as String)
        : null,
  );
}
```

--------------------------------

### Last Review Property

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/lastReview.html

Details about the 'lastReview' property, its type, and its getter/setter implementation.

```APIDOC
## Last Review Property

### Description
The date and time of the card's last review.

### Type
DateTime?

### Access
Getter/Setter pair

### Implementation
```dart
DateTime? lastReview;
```
```

--------------------------------

### State Enum Methods and Operators

Source: https://pub.dev/documentation/fsrs/latest/fsrs/State.html

Details the methods and operators available for the State enum, such as noSuchMethod, toString, and the equality operator (==). These are standard object methods inherited or provided by extensions.

```dart
noSuchMethod(Invocation invocation) → dynamic
tostring() → String
operator ==(Object other) → bool
```

--------------------------------

### Update Card State and Calculate Next Interval

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/reviewCard.html

Calculates the next stability, difficulty, and interval for a card based on the user's rating. It manages transitions between relearning and review states and applies optional fuzzing to the final interval.

```dart
card.stability = _shortTermStability(stability: card.stability!, rating: rating);
card.difficulty = _nextDifficulty(difficulty: card.difficulty!, rating: rating);
} else {
  card.stability = _nextStability(difficulty: card.difficulty!, stability: card.stability!, retrievability: getCardRetrievability(card, currentDateTime: reviewDateTime), rating: rating);
  card.difficulty = _nextDifficulty(difficulty: card.difficulty!, rating: rating);
}
if (relearningSteps.isEmpty || (card.step! >= relearningSteps.length && [Rating.hard, Rating.good, Rating.easy].contains(rating))) {
  card.state = State.review;
  card.step = null;
  final nextIntervalDays = _nextInterval(stability: card.stability!);
  nextInterval = Duration(days: nextIntervalDays);
} else {
  switch (rating) {
    case Rating.again:
      card.step = 0;
      nextInterval = relearningSteps[card.step!];
    case Rating.good:
      if (card.step! + 1 == relearningSteps.length) {
        card.state = State.review;
        card.step = null;
        final nextIntervalDays = _nextInterval(stability: card.stability!);
        nextInterval = Duration(days: nextIntervalDays);
      } else {
        card.step = card.step! + 1;
        nextInterval = relearningSteps[card.step!];
      }
  }
}
if (enableFuzzing && card.state == State.review) {
  nextInterval = _getFuzzedInterval(nextInterval);
}
card.due = reviewDateTime.add(nextInterval);
card.lastReview = reviewDateTime;
```

--------------------------------

### Due Property Implementation (Dart)

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Card/due.html

This snippet shows the basic implementation of the 'due' property, which stores the next due date and time for a card. It is declared as a DateTime object.

```Dart
DateTime due;
```

--------------------------------

### getCardRetrievability Method

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/getCardRetrievability.html

Calculates the retrievability of a card for a specified date and time. Retrievability represents the probability of correct recall.

```APIDOC
## getCardRetrievability

### Description
Calculates a Card object's current retrievability for a given date and time. The retrievability of a card is the predicted probability that the card is correctly recalled at the provided datetime.

### Method
N/A (This is a function, not a REST API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **retrievability** (double) - The calculated retrievability of the Card object.

#### Response Example
```json
{
  "retrievability": 0.85
}
```

### Args:
- **card** (Card) - The card whose retrievability is to be calculated.
- **currentDateTime** (DateTime?) - Optional. The current date and time. Defaults to `DateTime.now().toUtc()` if not provided.
```

--------------------------------

### Declare learningSteps Property (Dart)

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/learningSteps.html

This snippet shows the declaration of the 'learningSteps' property in Dart. It is a final List of Duration objects, intended to store small time intervals for scheduling cards in the Learning state.

```dart
final List<Duration> learningSteps;
```

--------------------------------

### Rating Property

Source: https://pub.dev/documentation/fsrs/latest/fsrs/ReviewLog/rating.html

Details the 'rating' property and its implementation.

```APIDOC
## Rating Property

### Description
The rating given to the card during the review.

### Implementation
```dart
final Rating rating;
```
```

--------------------------------

### Convert Scheduler to Map

Source: https://pub.dev/documentation/fsrs/latest/fsrs/Scheduler/toMap.html

This method serializes the Scheduler object into a Map structure. It converts duration-based lists like learningSteps and relearningSteps into seconds to ensure compatibility with storage systems.

```dart
Map<String, dynamic> toMap() {
  return {
    'parameters': parameters,
    'desiredRetention': desiredRetention,
    'learningSteps': learningSteps.map((step) => step.inSeconds).toList(),
    'relearningSteps': relearningSteps.map((step) => step.inSeconds).toList(),
    'maximumInterval': maximumInterval,
    'enableFuzzing': enableFuzzing,
  };
}
```

--------------------------------

### State Enum Static Method: fromValue

Source: https://pub.dev/documentation/fsrs/latest/fsrs/State.html

Provides the static method `fromValue` which allows creating a State enum instance from an integer value. This is useful for converting numeric representations back to enum states.

```dart
fromValue(int value) → State
```
Tokens:
Raw