MediaFileClaim

Overview

services/api/src/models/MediaFileClaim.js defines the Mongoose model that stores the claim for a single ImageKit file and binds it to exactly one Listing. The comments in the file describe it as the atomic piece that coordinates attaching media with deleting media, without transactions, by using _id = fileId as the unique key.

The model also records the claim lifecycle through the states active, deleting, erasing, and deleted. The same source explains that older Listing records created before this registry are treated as unclaimed, and deletion logic checks their references in media-claims.service.js.

[!IMPORTANT] The uniqueness guarantee comes from MongoDB’s default _id index. This file does not define any extra index or migration.

How it works

flowchart TD
    FileId[ImageKit fileId] --> Claim[MediaFileClaim]
    Claim --> Collection[media_file_claims]
    Claim --> Listing[Listing]
    Claim --> State[state]
    State --> Active[active]
    State --> Deleting[deleting]
    State --> Erasing[erasing]
    State --> Deleted[deleted]
    Claim --> Holder[holder]

The file maps one ImageKit fileId to one Listing through a single document in media_file_claims. The state field controls the claim lifecycle, while holder stores the operation that currently owns the claim during deletion phases. The schema is intentionally compact and relies on Mongoose defaults for timestamps and MongoDB’s built-in _id uniqueness.

Key components

The file exports one enum-like constant and one Mongoose model. Both are public module exports and are the only runtime symbols defined here.

{
    "title": "MediaFileClaim",
    "content": "Mongoose model that stores one claim document per ImageKit fileId and binds it to exactly one Listing.",
    "type": "class",
    "filePath": "services/api/src/models/MediaFileClaim.js",
    "badges": [
        "public"
    ]
}

{
    "title": "MEDIA_FILE_CLAIM_STATES",
    "content": "Read-only exported list of allowed claim states: active, deleting, erasing, and deleted.",
    "type": "enum",
    "filePath": "services/api/src/models/MediaFileClaim.js",
    "badges": [
        "public",
        "read-only"
    ]
}

Data & fields

The schema defines four fields and uses one collection-level configuration block. The shape is fixed in this file, and the state field is constrained by MEDIA_FILE_CLAIM_STATES.

[
    {
        "name": "_id",
        "type": "string",
        "required": true,
        "description": "Primary key and ImageKit fileId. The model uses it as the unique identifier for the claim."
    },
    {
        "name": "listingId",
        "type": "ObjectId",
        "required": true,
        "description": "Reference to Listing for the publication that owns the file."
    },
    {
        "name": "state",
        "type": "string",
        "required": true,
        "description": "Lifecycle state. Must match one value from MEDIA_FILE_CLAIM_STATES."
    },
    {
        "name": "holder",
        "type": "ObjectId",
        "description": "Identifier of the operation that acquired the claim. Defaults to null."
    }
]

Schema configuration

The schema enables timestamps and stores documents in the media_file_claims collection. It also disables Mongoose’s version key.

  • timestamps: true — Mongoose adds createdAt and updatedAt.
  • collection: "media_file_claims" — documents are stored in this collection.
  • versionKey: false — Mongoose does not create the __v field.

State values

The allowed values are fixed in the exported constant. The file defines the claim lifecycle as a closed set, not a free-form string field.

  • active — the file is attached or being attached to the Listing.
  • deleting — a deletion operation has acquired the claim.
  • erasing — the holder has confirmed possession and is calling ImageKit.
  • deleted — the file has already been removed from ImageKit and becomes a tombstone.

Behaviors

This file does not define custom methods, hooks, or static helpers. Its behavior comes from the schema definition and the exported model registration.

  • MEDIA_FILE_CLAIM_STATES — exports the allowed state list used by the schema enum.
  • MediaFileClaim — registers the MediaFileClaim model against the media_file_claims collection.
  • _id — acts as the fileId and enforces one claim per file through MongoDB’s default primary key uniqueness.
  • holder — stores the operation identifier that owns the claim while deletion is in progress.

Gotchas & edge cases

[!WARNING] Because _id is the fileId, a duplicate claim for the same file collides at the primary key level. The file relies on MongoDB’s built-in _id uniqueness instead of defining a custom index.

[!CAUTION] holder defaults to null. The field only becomes meaningful when a deletion operation acquires the claim and needs to keep ownership across later writes.

[!NOTE] The deleted state is described in the source as a permanent tombstone. The file’s comments say the file is not reassigned after ImageKit deletion.

[!IMPORTANT] The source explicitly treats older Listing records as “sin reclamar” and points deletion logic to media-claims.service.js for reference checks. That behavior is part of the surrounding media workflow, not of this schema alone.

This model connects directly to Listing through the listingId reference in the schema. The source also names services/api/src/modules/media/media-claims.service.js as the place that handles deletion logic for older listings without claim records. The comments tie the model to ImageKit file lifecycle management, so this file sits at the boundary between persistence and external media operations.

  • services/api/src/models/Listing.js — referenced by listingId via ref: "Listing".
  • services/api/src/modules/media/media-claims.service.js — named in the comments as the service that checks references for older listings.
  • ImageKit file lifecycle — the comments describe the attached, deleting, erasing, and deleted phases around ImageKit media.

Updated