@meith/polls 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@meith/polls",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/polls"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/i18n": "0.16.0",
+    "@meith/core": "0.16.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export {
+  POLL_CHOICES_UNLIMITED,
+  POLL_OPTION_LENGTH_MAX,
+  POLL_OPTION_MAX,
+  POLL_QUESTION_MAX,
+  POLL_VOTERS_SHOWN_MAX,
+  PollService,
+  planPollEdit,
+  ThreadRatingService,
+  validatePoll,
+} from './service'
+export type {
+  NewPoll,
+  Poll,
+  PollEdit,
+  PollEditCapabilities,
+  PollEditOption,
+  PollEditPlan,
+  PollOption,
+  PollRepository,
+  PollSettings,
+  PollVote,
+  PollVoter,
+  ThreadRating,
+  ThreadRatingRepository,
+  ValidatedPoll,
+} from './types'

package/src/service.ts

@@ -0,0 +1,231 @@
+import { ForbiddenError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import type {
+  NewPoll,
+  Poll,
+  PollEdit,
+  PollEditCapabilities,
+  PollEditOption,
+  PollEditPlan,
+  PollRepository,
+  PollSettings,
+  ThreadRating,
+  ThreadRatingRepository,
+  ValidatedPoll,
+} from './types'
+
+export const POLL_QUESTION_MAX = 250
+export const POLL_OPTION_MAX = 20
+export const POLL_OPTION_LENGTH_MAX = 200
+export const POLL_CHOICES_UNLIMITED = 0
+export const POLL_VOTERS_SHOWN_MAX = 50
+
+function trimmedQuestion(question: string): string {
+  const trimmed = question.trim()
+  if (trimmed.length === 0 || trimmed.length > POLL_QUESTION_MAX) {
+    throw new ValidationError(msg('error.polls.question-length', { max: POLL_QUESTION_MAX }))
+  }
+  return trimmed
+}
+
+function checkLabels(labels: readonly string[]): void {
+  if (labels.length < 2 || labels.length > POLL_OPTION_MAX) {
+    throw new ValidationError(msg('error.polls.option-count', { max: POLL_OPTION_MAX }))
+  }
+  if (labels.some((label) => label.length > POLL_OPTION_LENGTH_MAX)) {
+    throw new ValidationError(msg('error.polls.option-length', { max: POLL_OPTION_LENGTH_MAX }))
+  }
+  if (new Set(labels.map((label) => label.toLowerCase())).size !== labels.length) {
+    throw new ValidationError(msg('error.polls.poll-options-must-distinct'))
+  }
+}
+
+function checkClosesAt(closesAt: Date | null, now: Date): void {
+  if (closesAt !== null && closesAt <= now) {
+    throw new ValidationError(msg('error.polls.poll-must-close-future'))
+  }
+}
+
+function pollSettings(
+  input: {
+    readonly maxOptions?: number | undefined
+    readonly allowRevote?: boolean | undefined
+    readonly publicVotes?: boolean | undefined
+  },
+  optionCount: number,
+): PollSettings {
+  const maxOptions = input.maxOptions ?? 1
+  if (!Number.isInteger(maxOptions) || maxOptions < 0 || maxOptions > optionCount) {
+    throw new ValidationError(msg('error.polls.choice-limit', { max: optionCount }))
+  }
+  return {
+    maxOptions,
+    allowRevote: input.allowRevote ?? false,
+    publicVotes: input.publicVotes ?? false,
+  }
+}
+
+export function validatePoll(input: NewPoll, now = new Date()): ValidatedPoll {
+  const question = trimmedQuestion(input.question)
+  const options = input.options.map((option) => option.trim()).filter(Boolean)
+  checkLabels(options)
+  checkClosesAt(input.closesAt, now)
+  return { question, options, closesAt: input.closesAt, ...pollSettings(input, options.length) }
+}
+
+export function planPollEdit(poll: Poll, edit: PollEdit, now = new Date()): PollEditPlan {
+  const question = trimmedQuestion(edit.question)
+  const existing = new Map(poll.options.map((option) => [option.id, option]))
+  const options: PollEditOption[] = []
+  const kept = new Set<number>()
+
+  for (const option of edit.options) {
+    const label = option.label.trim()
+    if (label === '') continue
+    if (option.id === null) {
+      options.push({ id: null, label })
+      continue
+    }
+    if (!existing.has(option.id)) {
+      throw new ValidationError(msg('error.polls.option-not-on-poll'))
+    }
+    if (kept.has(option.id)) {
+      throw new ValidationError(msg('error.polls.poll-options-must-distinct'))
+    }
+    kept.add(option.id)
+    options.push({ id: option.id, label })
+  }
+
+  checkLabels(options.map((option) => option.label))
+
+  const removedOptionIds = poll.options
+    .filter((option) => !kept.has(option.id))
+    .map((option) => option.id)
+  if (removedOptionIds.some((id) => (existing.get(id)?.votes ?? 0) > 0)) {
+    throw new ValidationError(msg('error.polls.remove-voted-option'))
+  }
+
+  if (edit.closesAt?.getTime() !== poll.closesAt?.getTime()) checkClosesAt(edit.closesAt, now)
+
+  const settings = pollSettings(edit, options.length)
+  const cast = poll.options.reduce((sum, option) => sum + option.votes, 0)
+  if (settings.publicVotes && !poll.publicVotes && cast > 0) {
+    throw new ValidationError(msg('error.polls.public-after-voting'))
+  }
+
+  return {
+    pollId: poll.id,
+    question,
+    closesAt: edit.closesAt,
+    options,
+    removedOptionIds,
+    ...settings,
+  }
+}
+
+export class PollService {
+  constructor(
+    private readonly polls: PollRepository,
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+
+  async attach(threadId: number, poll: NewPoll): Promise<void> {
+    await this.polls.create(threadId, validatePoll(poll, this.now()))
+  }
+
+  async vote(input: {
+    readonly threadId: number
+    readonly pollId: number
+    readonly optionIds: readonly number[]
+    readonly userId: number
+    readonly mayVote: boolean
+  }): Promise<void> {
+    if (!input.mayVote) throw new ForbiddenError(msg('error.polls.vote-polls'))
+
+    const poll = await this.load(input.threadId, input.pollId, input.userId)
+    if (poll.closesAt !== null && poll.closesAt <= this.now()) {
+      throw new ValidationError(msg('error.polls.poll-closed'))
+    }
+    if (poll.votedOptionIds.length > 0 && !poll.allowRevote) {
+      throw new ValidationError(msg('error.polls.already-voted'))
+    }
+
+    const chosen = [...new Set(input.optionIds)]
+    if (chosen.length === 0) throw new ValidationError(msg('error.polls.choose-option'))
+
+    const available = new Set(poll.options.map((option) => option.id))
+    if (chosen.some((id) => !available.has(id))) {
+      throw new ValidationError(msg('error.polls.option-not-on-poll'))
+    }
+    if (poll.maxOptions !== POLL_CHOICES_UNLIMITED && chosen.length > poll.maxOptions) {
+      throw new ValidationError(msg('error.polls.choose-at-most', { max: poll.maxOptions }))
+    }
+
+    const stored = await this.polls.vote({
+      threadId: input.threadId,
+      pollId: input.pollId,
+      optionIds: chosen,
+      userId: input.userId,
+    })
+    if (!stored) throw new ValidationError(msg('error.polls.poll-closed-already-voted'))
+  }
+
+  async edit(input: {
+    readonly threadId: number
+    readonly pollId: number
+    readonly edit: PollEdit
+    readonly capabilities: PollEditCapabilities
+  }): Promise<void> {
+    const { capabilities } = input
+    if (!capabilities.isAuthor && !capabilities.mayEditOthers) {
+      throw new ForbiddenError(msg('error.polls.edit-poll'))
+    }
+
+    const poll = await this.load(input.threadId, input.pollId, null)
+    this.enforceEditWindow(poll, capabilities)
+
+    if (!(await this.polls.applyEdit(planPollEdit(poll, input.edit, this.now())))) {
+      throw new ValidationError(msg('error.polls.poll-exist'))
+    }
+  }
+
+  private async load(threadId: number, pollId: number, userId: number | null): Promise<Poll> {
+    const poll = await this.polls.find(threadId, userId)
+    if (poll === null || poll.id !== pollId) {
+      throw new ValidationError(msg('error.polls.poll-exist'))
+    }
+    return poll
+  }
+
+  private enforceEditWindow(poll: Poll, capabilities: PollEditCapabilities): void {
+    if (!capabilities.isAuthor || capabilities.mayEditOthers || capabilities.bypassesWindow) return
+    if (capabilities.editWindowMinutes <= 0) return
+
+    const elapsed = (this.now().getTime() - poll.createdAt.getTime()) / 60_000
+    if (elapsed <= capabilities.editWindowMinutes) return
+
+    throw new ValidationError(
+      msg('error.polls.edit-window', { minutes: capabilities.editWindowMinutes }),
+    )
+  }
+}
+
+export class ThreadRatingService {
+  constructor(private readonly ratings: ThreadRatingRepository) {}
+
+  async rate(input: {
+    readonly threadId: number
+    readonly userId: number
+    readonly rating: number
+    readonly enabled: boolean
+  }): Promise<ThreadRating> {
+    if (!input.enabled) throw new ForbiddenError(msg('error.polls.thread-ratings-switched-off'))
+    if (!Number.isInteger(input.rating) || input.rating < 1 || input.rating > 5) {
+      throw new ValidationError(msg('error.polls.choose-rating-from-1-5'))
+    }
+    const result = await this.ratings.rate(input)
+    if (result === null) throw new ValidationError(msg('error.polls.thread-exist'))
+    return result
+  }
+}

package/src/types.ts

@@ -0,0 +1,101 @@
+export interface PollSettings {
+  readonly maxOptions: number
+  readonly allowRevote: boolean
+  readonly publicVotes: boolean
+}
+
+export interface NewPoll {
+  readonly question: string
+  readonly options: readonly string[]
+  readonly closesAt: Date | null
+  readonly maxOptions?: number | undefined
+  readonly allowRevote?: boolean | undefined
+  readonly publicVotes?: boolean | undefined
+}
+
+export interface ValidatedPoll extends PollSettings {
+  readonly question: string
+  readonly options: readonly string[]
+  readonly closesAt: Date | null
+}
+
+export interface PollVoter {
+  readonly userId: number
+  readonly username: string
+  readonly votedAt: Date | null
+}
+
+export interface PollOption {
+  readonly id: number
+  readonly label: string
+  readonly votes: number
+  readonly voters: readonly PollVoter[]
+}
+
+export interface Poll extends PollSettings {
+  readonly id: number
+  readonly threadId: number
+  readonly question: string
+  readonly closesAt: Date | null
+  readonly createdAt: Date
+  readonly options: readonly PollOption[]
+  readonly votedOptionIds: readonly number[]
+}
+
+export interface PollEditOption {
+  readonly id: number | null
+  readonly label: string
+}
+
+export interface PollEdit {
+  readonly question: string
+  readonly options: readonly PollEditOption[]
+  readonly closesAt: Date | null
+  readonly maxOptions?: number | undefined
+  readonly allowRevote?: boolean | undefined
+  readonly publicVotes?: boolean | undefined
+}
+
+export interface PollEditPlan extends PollSettings {
+  readonly pollId: number
+  readonly question: string
+  readonly closesAt: Date | null
+  readonly options: readonly PollEditOption[]
+  readonly removedOptionIds: readonly number[]
+}
+
+export interface PollVote {
+  readonly threadId: number
+  readonly pollId: number
+  readonly optionIds: readonly number[]
+  readonly userId: number
+}
+
+export interface PollEditCapabilities {
+  readonly isAuthor: boolean
+  readonly mayEditOthers: boolean
+  readonly editWindowMinutes: number
+  readonly bypassesWindow: boolean
+}
+
+export interface PollRepository {
+  create(threadId: number, poll: ValidatedPoll): Promise<void>
+  find(threadId: number, voterUserId: number | null): Promise<Poll | null>
+  vote(input: PollVote): Promise<boolean>
+  applyEdit(plan: PollEditPlan): Promise<boolean>
+}
+
+export interface ThreadRating {
+  readonly average: number
+  readonly count: number
+  readonly mine: number | null
+}
+
+export interface ThreadRatingRepository {
+  rate(input: {
+    readonly threadId: number
+    readonly userId: number
+    readonly rating: number
+  }): Promise<ThreadRating | null>
+  findRating(threadId: number, userId: number | null): Promise<ThreadRating | null>
+}