PositionService

Source: PositionService.js:41

Service for managing position entities and their associations. Handles CRUD operations and position-specific logic.

Constructor

Instance Methods

create( x: number, y: number, LineupId: UUID, MemberId: UUID, actingUserId: UUID, isAdmin?: boolean, timeOfManualUpdate?: Date, ): Promise.<Object>

Create a new position.

Parameters

• x (number) — The x-coordinate of the position.
• y (number) — The y-coordinate of the position.
• LineupId (UUID) — The lineup ID associated with the position.
• MemberId (UUID) — The member ID placed at the position.
• actingUserId (UUID) — The acting user ID.
• isAdmin (boolean, optional, default: false)
• timeOfManualUpdate (Date, optional, default: "new Date()")

Returns

• Promise.<Object> — The created position.

findOrCreate( x: number, y: number, LineupId: UUID, MemberId: UUID, actingUserId: UUID, timeOfManualUpdate?: Date, ): Promise.<Object>

Find or create a position.

Parameters

• x (number) — The x-coordinate of the position.
• y (number) — The y-coordinate of the position.
• LineupId (UUID) — The lineup ID associated with the position.
• MemberId (UUID) — The member ID associated with the position.
• actingUserId (UUID) — The acting user ID.
• timeOfManualUpdate (Date, optional, default: "new Date()")

Returns

• Promise.<Object> — The found or created position.

findByLineupId( LineupId: UUID, ownerIds: Array.<UUID>, actingUserId: UUID, ): Promise.<Array>

Get all positions for a lineup.

Parameters

• LineupId (UUID) — The lineup ID.
• ownerIds (Array.<UUID>) — Array of owner IDs the acting user has access to.
• actingUserId (UUID) — The acting user ID.

Returns

• Promise.<Array> — List of positions.

findById(id: UUID, actingUserId: UUID): Promise.<(Object|null)>

Find a position by ID.

Parameters

• id (UUID) — The ID of the position.
• actingUserId (UUID) — The acting user ID.

Returns

• Promise.<(Object|null)> — The found position or null if not found.

update( id: UUID, lineupId: string | null, data: Object, actingUserId: UUID, isAdmin?: boolean, ): Promise.<Object>

Update a position's coordinates, timestamp, or member.

A position cannot be moved to another lineup: a LineupId/lineupId in data that differs from the current lineup is rejected. Reassigning the member is allowed but validated for existence and run under the lineup conflict guard so it cannot create a member conflict or duplicate position. The timeOfManualUpdate acts as a last-write-wins guard against stale, out-of-order updates.

Parameters

• id (UUID) — The ID of the position.
• lineupId (string | null) — If set, the position must belong to this lineup or it is treated as not found (ownership/path filter).
• data (Object) — Fields to update.
  • data.timeOfManualUpdate (Date, optional) — Client update time; an older value than the stored one is ignored.
  • data.x (number, optional) — New x-coordinate.
  • data.y (number, optional) — New y-coordinate.
  • data.MemberId (UUID, optional) — New member to place; validated and guarded.
  • data.LineupId (UUID, optional) — Must equal the current lineup if provided.
  • data.lineupId (UUID, optional) — Lowercase alias of LineupId; same rule.
• actingUserId (UUID) — The acting user ID.
• isAdmin (boolean, optional, default: false) — Whether the acting user is an admin.

Returns

• Promise.<Object> — The updated position.

Throws

• NotFoundError — If the position (optionally scoped to lineupId) or a reassigned member is not found.
• FaultyInputError — If data tries to move the position to another lineup.
• RequestOrderError — If timeOfManualUpdate is not newer than the stored value.
• LineupConflictError — If a member reassignment introduces a conflict.

remove(id: UUID, actingUserId: UUID): Promise.<void>

Remove a position.

Parameters

• id (UUID) — The ID of the position.
• actingUserId (UUID) — The acting user ID.

Returns

• Promise.<void> — Resolves when the position is removed.

Throws

• Will throw an error if the position is not found.

bulkFindOrCreate( positions: Array.<{x: number, y: number, memberId: string}>, LineupId: string, actingUserId: string, isAdmin: boolean, ): Promise.<Array>

Bulk find-or-create positions for a lineup. Performs access checks once, then creates all positions.

Parameters

• positions (Array.<{x: number, y: number, memberId: string}>) — Position data.
• LineupId (string) — The lineup ID.
• actingUserId (string) — The acting user ID.
• isAdmin (boolean, default: false) — Whether the acting user is an admin.

Returns

• Promise.<Array> — Array of created or found positions.

mcpFindOrCreate()

MCP-optimized: Find or create a single position with lightweight access checks. Avoids loading the full Lineup/Choreo object graph.

mcpBulkFindOrCreate()

MCP-optimized: Bulk find-or-create positions with lightweight access checks. Avoids loading the full Lineup/Choreo object graph.