funoteka 0.1.0

package/dist/playlist/files.js

@@ -0,0 +1,116 @@
+import { dirname, isAbsolute, resolve } from 'node:path';
+/**
+ * The `.m3u` files lying in the collection.
+ *
+ * A playlist file is two very different things depending on what is in it, and
+ * the difference is not in its name or its size — it is in where its entries
+ * point. A `.m3u` written beside an album, listing that album's tracks, says
+ * nothing the folder tree does not already say: it is *redundant*, and offering
+ * it as a playlist would put every record in the library into a client's
+ * playlist list twice. One whose entries come from several folders is a list
+ * somebody made on purpose, and that is the kind worth importing.
+ *
+ * This module decides that and nothing else — it reads text, not the meta
+ * layer, and knows nothing about tracks. Matching entries to songs is the
+ * stage's business (`playlist/import.ts`, run by `run.ts` after `cues`),
+ * because it is the stage that has a database.
+ *
+ * Nothing here reads a file: the bytes are decoded by `text/encoding.ts` and
+ * handed over as a string, so a playlist in CP1251 is the same problem as an
+ * `.nfo` in CP1251 and is solved in the same place.
+ */
+/**
+ * The entries of a playlist file, in the order it states them.
+ *
+ * Three dialects arrive in the same collection and all three are handled:
+ * a bare list of paths, the extended form where every path is preceded by
+ * `#EXTINF:` lines, and the same with the paths quoted. Comments and directives
+ * start with `#` and are dropped — an `#EXTINF` line carries a duration and a
+ * title, and neither is used: the file says *which* songs and in what order,
+ * and what each song is called is a fact about the song.
+ *
+ * A byte-order mark leading the file is dropped with them. It is three bytes of
+ * `EF BB BF` that a Windows editor wrote, and left in place it becomes the
+ * first character of the first path — a file that cannot be found, in a list
+ * where every other entry resolves.
+ */
+export function parseEntries(text) {
+    return text
+        .replace(/^\uFEFF/, '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line !== '' && !line.startsWith('#'))
+        .map((line) => unquote(line))
+        .filter((line) => line !== '');
+}
+/** A path a playlist wrote the way a person would — sometimes in quotes. */
+function unquote(line) {
+    const quoted = /^"(.*)"$/.exec(line) ?? /^'(.*)'$/.exec(line);
+    return (quoted?.[1] ?? line).trim();
+}
+/**
+ * What an entry points at, as a path — or nothing, when it points out of the
+ * filesystem altogether.
+ *
+ * A playlist may name a stream (`http://…`), and no folder will ever hold one.
+ * Those entries are dropped here rather than resolved into a nonsense path: the
+ * question this module answers is about *folders*, and a URL has none.
+ */
+export function resolveEntry(entry, folder) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(entry))
+        return null;
+    // A Windows path may be written with either separator, and both arrive: an
+    // absolute `C:\Music\…` from a ripping tool and a relative `01 - x.flac` from
+    // a person. `resolve` handles the second and understands both separators of
+    // the first on Windows; on other platforms an absolute Windows path is not a
+    // path, and the entry resolves relative to the folder like any other string.
+    return resolve(isAbsolute(entry) ? entry : folder, entry);
+}
+/**
+ * How the folders of a playlist compare.
+ *
+ * Case-folded on Windows and not elsewhere, because that is what the two
+ * filesystems do: `C:\Music\A` and `c:\music\a` are one folder there and two
+ * paths anywhere else. Getting this wrong in the other direction would call a
+ * curated list redundant — the mistake this classification exists to avoid —
+ * so it follows the platform rather than a preference.
+ */
+function folderKey(path) {
+    return process.platform === 'win32' ? path.toLowerCase() : path;
+}
+/**
+ * What a playlist file is: the album it sits beside, or a list of its own.
+ *
+ * One folder — or none — is redundant. That covers the ordinary case (a `.m3u`
+ * beside an album, listing that album) and the degenerate ones (an empty file,
+ * a file listing only one song): none of them is a list a client should be
+ * offered, and importing them would fill the playlist list with the library
+ * itself.
+ *
+ * More than one folder is curated. This is deliberately a question about
+ * *folders* and not about albums or artists: a playlist of one artist's records
+ * is exactly the case worth importing, and so is a mix, while a playlist of one
+ * album from two folders is a record this collection filed in two places and
+ * still says nothing new.
+ *
+ * Named `readingOf` and not `classify`, which in this project is a stage: the
+ * folder classifier that decides what an *album* is. Two questions a word apart
+ * and nothing else in common.
+ */
+export function readingOf(entries, folder) {
+    const folders = new Set();
+    const paths = [];
+    for (const entry of entries) {
+        const path = resolveEntry(entry, folder);
+        if (path === null)
+            continue;
+        paths.push(path);
+        folders.add(folderKey(dirname(path)));
+    }
+    return {
+        verdict: folders.size > 1 ? 'curated' : 'redundant',
+        entries: entries.length,
+        folders: folders.size,
+        paths,
+    };
+}

package/dist/playlist/import.js

@@ -0,0 +1,260 @@
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { withTransaction } from "../db/index.js";
+import { clearIssues } from "../db/issue.js";
+import { ledgerEntry, moved } from "../db/ledger.js";
+import { decodeText } from "../text/encoding.js";
+import { basenameOf, stemOf } from "../util/names.js";
+import { parseEntries, readingOf } from "./files.js";
+import * as store from "./store.js";
+/**
+ * The playlist files the collection carries, read and weighed.
+ *
+ * A `.m3u` is either the album it sits beside or a list somebody made, and
+ * `files.ts` decides which — this stage is where that decision meets the meta
+ * layer. The two outcomes are handled very differently on purpose:
+ *
+ *   - **redundant** (every entry in one folder) is *ignored*, and an issue says
+ *     so. The folder tree already offers that music; importing it would list
+ *     every album in the library a second time, under a name a client shows
+ *     beside real playlists.
+ *   - **curated** becomes a playlist, found by the file it came from rather
+ *     than by its name, so reading the same file again updates that playlist
+ *     instead of making another one. The row keeps the file it came from, which
+ *     is also what tells the API that this playlist is the file's and not the
+ *     listener's (`playlist/store.ts`).
+ *
+ * A file that stops being curated takes its playlist with it, and so does one
+ * that stops naming anything this library holds: the list is the file's, and a
+ * row left behind by a file that no longer asks for it is a list the collection
+ * does not have. So does a file that is deleted, through the cascade on
+ * `playlist.source_file_id`.
+ *
+ * **What is measured on this collection:** of 27 playlist files, all 27 name
+ * songs from one folder each and not one reaches outside the folder it sits in.
+ * The curated branch is therefore the one this library never exercises — which
+ * is why it is the branch the tests do.
+ */
+/** This stage's name in `issue.stage`. Bound to the insert and to the clear. */
+const STAGE = 'playlists';
+/**
+ * Read the collection's playlist files, and import the ones that are lists.
+ *
+ * Runs after `cues`, and that is not a preference: an imported playlist names
+ * songs, and songs exist only once the cue stage has written them.
+ *
+ * The whole pass is one transaction, like every other stage that writes: it
+ * reads a file, asks several questions of the meta layer and writes what it
+ * concluded, and a scan that fell over halfway through should leave none of it
+ * behind. Measured on the live meta layer, a hundred writes outside a
+ * transaction cost 4452 ms against 74 ms inside one — the stage that reads
+ * every playlist in a collection is not the place to pay that again.
+ */
+export function applyPlaylists(db, deps = {}) {
+    const counters = {
+        files: 0,
+        filesRead: 0,
+        redundant: 0,
+        curated: 0,
+        imported: 0,
+        unchanged: 0,
+        entriesMissing: 0,
+        unreadable: 0,
+        issues: 0,
+    };
+    const latest = db.prepare('SELECT MAX(id) AS id FROM scan_run').get();
+    if (latest.id === null)
+        return counters;
+    const readBytes = deps.readBytes ?? ((absPath) => readFileSync(absPath));
+    // Every playlist file of this run is taken up on every run, and its *bytes*
+    // are read only when there are none kept or the ledger says they moved — the
+    // same rule the tag stage follows for the record's documentation, and the same
+    // table: `sidecar_text` holds what the bytes said, so a playlist in CP1251 is
+    // decoded once.
+    //
+    // Taken up every time on purpose, and that is not the same question. A `.m3u`
+    // that did not change still describes a *library* that may have: a song it
+    // names can be deleted, and the playlist imported from it should lose that
+    // song. Skipping the files the ledger calls unmoved would leave the playlist
+    // holding what the collection no longer has, which is the one thing an
+    // imported list must never do. Re-reading the text is what the cache saves;
+    // the verdict is reached again from it, and nothing is written unless it
+    // changed (see `sameSongs`).
+    const due = db
+        .prepare(`SELECT f.id, f.rel_path, f.root_id, r.path AS root_path, f.ext,
+              st.text AS cached_text, ${moved('ss')} AS moved
+         FROM file f
+         JOIN root r ON r.id = f.root_id
+         LEFT JOIN scan_state ss ON ${ledgerEntry('f', 'ss')}
+         LEFT JOIN sidecar_text st ON st.file_id = f.id
+        WHERE f.kind = 'playlist' AND f.last_seen_run_id = ?
+        ORDER BY f.root_id, f.rel_path`)
+        .all(latest.id);
+    const upsertText = db.prepare(`INSERT INTO sidecar_text (file_id, text) VALUES (?, ?)
+     ON CONFLICT (file_id) DO UPDATE SET text = excluded.text`);
+    const stampEncoding = db.prepare('UPDATE file SET encoding = ?, encoding_confidence = ? WHERE id = ?');
+    // A path may be spelled with either separator, and the meta layer holds the
+    // forward one (`scan/walk.ts` normalises it there). Case is folded on Windows
+    // and not elsewhere, because that is what the two filesystems do — a list that
+    // says `01.FLAC` names the file on one and not on the other.
+    const samePath = process.platform === 'win32' ? 'COLLATE NOCASE' : '';
+    const fileIdOf = db.prepare(`SELECT f.id AS id FROM file f WHERE f.root_id = ? AND f.rel_path = ? ${samePath}`);
+    const songsOfFile = db.prepare(`SELECT t.id AS id FROM track t JOIN file f ON f.id = t.file_id
+      WHERE f.root_id = ? AND f.rel_path = ? ${samePath}
+      ORDER BY t.ordinal, t.id`);
+    const nameTaken = db.prepare(`SELECT 1 AS taken FROM playlist
+      WHERE name = ? AND (source_file_id IS NULL OR source_file_id <> ?)`);
+    const isTaken = (name, fileId) => nameTaken.get(name, fileId) !== undefined;
+    const insertIssue = db.prepare(`INSERT INTO issue (scan_run_id, stage, root_id, rel_path, kind, severity, detail)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`);
+    const complain = (row, kind, severity, detail) => {
+        insertIssue.run(latest.id, STAGE, row.root_id, row.rel_path, kind, severity, detail);
+        counters.issues += 1;
+    };
+    withTransaction(db, () => {
+        for (const row of due) {
+            clearIssues(db, STAGE, { rootId: row.root_id, relPath: row.rel_path });
+            // The one format this does not read. `.pls` is a different document — an
+            // INI with numbered `FileN=` keys — and pretending otherwise would be
+            // worse than saying so: a `.pls` read as an `.m3u` yields no entries at
+            // all, and "redundant" would be the answer to a question nobody asked.
+            if (row.ext !== 'm3u' && row.ext !== 'm3u8') {
+                complain(row, 'playlist-format-not-read', 'info', `.${row.ext} is not read`);
+                continue;
+            }
+            let text = row.cached_text;
+            if (text === null || row.moved === 1) {
+                try {
+                    const decoded = decodeText(readBytes(join(row.root_path, row.rel_path)));
+                    text = decoded.text;
+                    counters.filesRead += 1;
+                    upsertText.run(row.id, text);
+                    stampEncoding.run(decoded.encoding, decoded.confidence, row.id);
+                    if (decoded.confidence < 1) {
+                        complain(row, 'playlist-encoding-guessed', 'info', decoded.basis ?? `${decoded.encoding} was inferred`);
+                    }
+                }
+                catch (err) {
+                    counters.unreadable += 1;
+                    complain(row, 'playlist-unreadable', 'warn', err.message);
+                    continue;
+                }
+            }
+            // Counted here rather than at the top of the loop: a `.pls` was taken up
+            // and refused, and a file that would not open was not read at all — the
+            // report says "read", and this is the number that keeps that word true.
+            counters.files += 1;
+            const folder = dirname(join(row.root_path, row.rel_path));
+            const entries = parseEntries(text);
+            const reading = readingOf(entries, folder);
+            // Both verdicts need this: a redundant list is only *the folder* if its
+            // entries are the folder's files, and one carried from another machine
+            // names nothing here — calling that "already offered by the folder" would
+            // be a false account of a list that was quietly dropped.
+            const songs = [];
+            let missing = 0;
+            for (const path of reading.paths) {
+                const rel = within(row.root_path, path);
+                if (rel === null) {
+                    missing += 1;
+                    continue;
+                }
+                const found = fileIdOf.get(row.root_id, rel);
+                if (found === undefined) {
+                    missing += 1;
+                    continue;
+                }
+                if (reading.verdict === 'curated') {
+                    for (const song of songsOfFile.all(row.root_id, rel))
+                        songs.push(song.id);
+                }
+            }
+            if (reading.verdict === 'redundant') {
+                store.removeBySourceFile(db, row.id);
+                counters.redundant += 1;
+                complain(row, 'playlist-redundant', 'info', missing > 0
+                    ? `${reading.entries} entries in ${reading.folders} folder${reading.folders === 1 ? '' : 's'}, ${missing} of them naming nothing here — the folder already offers this`
+                    : `${reading.entries} entries in ${reading.folders} folder${reading.folders === 1 ? '' : 's'} — the folder already offers this`);
+                continue;
+            }
+            counters.curated += 1;
+            counters.entriesMissing += missing;
+            if (missing > 0) {
+                complain(row, 'playlist-entries-missing', 'warn', `${missing} of ${entries.length} entries name no song in this library`);
+            }
+            if (songs.length === 0) {
+                // Curated by where it points, but nothing in it lands here — a list made
+                // on another machine, or one whose music was never scanned. An empty
+                // playlist would be a promise this library cannot keep, and one left over
+                // from a previous reading of this file would be a list it no longer says.
+                store.removeBySourceFile(db, row.id);
+                complain(row, 'playlist-nothing-imported', 'warn', `no entry of ${entries.length} names a song here`);
+                continue;
+            }
+            const name = nameFor(row, isTaken);
+            const existing = store.bySourceFile(db, row.id);
+            if (existing === undefined) {
+                store.create(db, name, songs, row.id);
+                counters.imported += 1;
+            }
+            else if (existing.name !== name || !sameSongs(db, existing.id, songs)) {
+                store.replace(db, existing.id, name, songs);
+                counters.imported += 1;
+            }
+            else {
+                // The file says what the playlist already says. Writing it again would
+                // move `changed_at`, and a client that syncs by that stamp would re-read
+                // a playlist because a scan ran — the same reasoning as `store.edit`'s
+                // silence when nothing changes.
+                counters.unchanged += 1;
+            }
+            complain(row, 'playlist-imported', 'info', `${songs.length} songs from ${reading.folders} folders`);
+        }
+    });
+    return counters;
+}
+/** Whether a playlist already holds exactly these songs, in this order. */
+function sameSongs(db, playlistId, songs) {
+    const held = store.entriesOf(db, playlistId);
+    return held.length === songs.length && held.every((id, at) => id === songs.at(at));
+}
+/**
+ * What to call an imported playlist.
+ *
+ * The file's own name, and the folder it sits in when that name is already
+ * taken by another playlist. Two `a.m3u` in two folders are two lists, and a
+ * sidebar showing `a` twice is a sidebar where one of them cannot be chosen —
+ * the same argument the project settled for records whose names collide
+ * ([[wiki:3602]]). The name is not the identity here either: the row is found
+ * by its file, and this is only what a person reads.
+ */
+function nameFor(row, isTaken) {
+    const stem = stemOf(basename(row.rel_path));
+    if (!isTaken(stem, row.id))
+        return stem;
+    const parent = basenameOf(dirname(row.rel_path));
+    return parent === '' ? stem : `${stem} (${parent})`;
+}
+/**
+ * Where a path lies inside the root, in the spelling the meta layer uses — or
+ * nothing, when it lies outside it.
+ *
+ * Outside is not a failure of the list: a curated playlist made elsewhere may
+ * name music this library does not have, and those entries are counted and
+ * reported rather than resolved into a path that cannot exist. `..odd.flac`
+ * inside the root is a file, though, and is not confused with `../odd.flac` —
+ * hence the separator rather than a bare prefix test.
+ *
+ * The collection has more than one root, and this stage asks about one at a
+ * time: a list may name music that lives under *another* root of the same
+ * collection, and that entry is reported as unmatched. Doing better means
+ * resolving against every root, which is a change to make when a collection
+ * actually has a `.m3u` that reaches across its own roots — measured on this
+ * one, none does.
+ */
+function within(rootPath, absPath) {
+    const rel = relative(rootPath, absPath);
+    if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || /^[a-z]:/i.test(rel))
+        return null;
+    return rel.split('\\').join('/');
+}

package/dist/playlist/store.js

@@ -0,0 +1,240 @@
+import { withTransaction } from "../db/index.js";
+/**
+ * Playlists, and who owns which of them.
+ *
+ * Two kinds of row live in the same two tables and they have two different
+ * authors, which is the whole of what a reader has to know before touching one:
+ *
+ *   - **The listener's**, written by the API: a statement about the music that
+ *     lives nowhere on disk. Nothing else writes these.
+ *   - **A file's**, imported by the playlist stage from a `.m3u` in the
+ *     collection (`playlist/import.ts`): the row is a reading of that file, and
+ *     the file is what the list *is*. A scan rewrites it from the file, and the
+ *     API refuses to edit or delete it — see below.
+ *
+ * `source_file_id` is the field that tells them apart: `NULL` is the listener's
+ * and a file id is that file's. It is not decoration, and the two rules that
+ * hang off it are the reason this module has a doc comment at all:
+ *
+ *   1. An imported row is rewritten on every scan that re-reads its file, so an
+ *      edit made through the API would survive exactly until the next scan. The
+ *      API therefore does not accept one, and says so (`api/playlist.ts`).
+ *   2. The row is the file's, so the file's removal takes it — through the
+ *      cascade, and through the stage when a file stops being a list.
+ *
+ * What this module does *not* read is the collection. A playlist's songs are
+ * read in `api/meta.ts` with every other song, by the same select, so a song in
+ * a playlist is the same song as everywhere else — and the question this module
+ * has about the collection, whether a track exists, is asked there too.
+ *
+ * Order is the whole of the domain here. `position` is a sequence laid out from
+ * zero by every write, because the protocol addresses entries by index —
+ * `songIndexToRemove` is a position — so every mutation below finishes by
+ * writing the order it left behind rather than trusting the arithmetic of the
+ * one before it. A song dropped by the cascade leaves its number unused until
+ * the next write; nothing reads the number as a position, only as an order.
+ */
+/**
+ * The number the next playlist gets.
+ *
+ * Read and moved on in the same transaction as the insert that uses it, so two
+ * callers cannot be handed the same number. See migration 025 for why the
+ * number comes from a table of its own rather than from the rows it numbers.
+ */
+function nextId(db) {
+    const row = db.prepare('SELECT next FROM playlist_sequence WHERE only_row = 1').get();
+    db.prepare('UPDATE playlist_sequence SET next = ? WHERE only_row = 1').run(row.next + 1);
+    return row.next;
+}
+/**
+ * When the playlist last moved, touched by every mutation that changes it.
+ *
+ * Reads and writes share the value: `changed_at` is written by the same
+ * statement that writes the change, so a client syncing by it can never see a
+ * change without the stamp that announces it.
+ */
+const TOUCH = 'changed_at = ?';
+/**
+ * Everything a playlist is, with the numbers and the picture a client draws
+ * beside it.
+ *
+ * Counted over the entries rather than over distinct tracks: a song twice in one
+ * playlist is two entries and two plays, and `songCount` is what the client
+ * shows beside the length of the list.
+ *
+ * The picture is the first entry's song, and it is taken by a correlated
+ * subquery — which this project has paid for once already (`ALBUM_GENRES` in
+ * `api/meta.ts`) and which is allowed here for the reason it was wrong there.
+ * The question is `MIN(position)` for one playlist, and the primary key of
+ * `playlist_track` is `(playlist_id, position)`: the answer is the first row of
+ * an index range, not a scan. Measured on 15 000 entries, a form that grouped
+ * every playlist's entries before the `WHERE` could narrow anything cost
+ * 5137 µs per call — against this one, which reads one index range. A playlist
+ * with no entries matches nothing and is handed no picture.
+ */
+const PLAYLIST_SELECT = `
+  SELECT p.id, p.name, p.comment, p.source_file_id, p.public, p.created_at, p.changed_at,
+         COUNT(pt.track_id) AS song_count,
+         SUM(t.duration_ms) AS duration_ms,
+         ft.album_id AS cover_album_id,
+         ft.id AS cover_track_id
+    FROM playlist p
+    LEFT JOIN playlist_track pt ON pt.playlist_id = p.id
+    LEFT JOIN track t ON t.id = pt.track_id
+    LEFT JOIN playlist_track fp ON fp.playlist_id = p.id
+      AND fp.position = (SELECT MIN(first_pt.position) FROM playlist_track first_pt
+                          WHERE first_pt.playlist_id = p.id)
+    LEFT JOIN track ft ON ft.id = fp.track_id
+`;
+export function playlists(db) {
+    return db
+        .prepare(`${PLAYLIST_SELECT}
+        GROUP BY p.id
+        ORDER BY p.name COLLATE NOCASE, p.id`)
+        .all();
+}
+export function playlist(db, id) {
+    return db
+        .prepare(`${PLAYLIST_SELECT} WHERE p.id = ? GROUP BY p.id`)
+        .get(id);
+}
+/**
+ * The entries of a playlist, in the order it holds them.
+ *
+ * The ids alone, because what a caller does with them is decide what to keep:
+ * this is read by the mutations below, which reason about the list as a
+ * sequence of tracks, and by nothing that renders.
+ */
+export function entriesOf(db, playlistId) {
+    return db
+        .prepare('SELECT track_id FROM playlist_track WHERE playlist_id = ? ORDER BY position')
+        .all(playlistId).map((row) => row.track_id);
+}
+/**
+ * Write a playlist's entries as the order given.
+ *
+ * The one place positions are assigned, and it assigns all of them: every
+ * mutation above ends here with the list it decided on, so no caller has to be
+ * right about gaps, shifts or the arithmetic of a removal. Rewriting the whole
+ * list is cheaper than proving an incremental update left no hole, and the
+ * protocol sets no ceiling on how long a playlist may be — measured, a hundred
+ * entries cost 74 ms inside the transaction that carries them.
+ */
+function writeEntries(db, playlistId, tracks) {
+    db.prepare('DELETE FROM playlist_track WHERE playlist_id = ?').run(playlistId);
+    const insert = db.prepare('INSERT INTO playlist_track (playlist_id, position, track_id) VALUES (?, ?, ?)');
+    tracks.forEach((trackId, position) => insert.run(playlistId, position, trackId));
+}
+/**
+ * A new playlist holding the songs named.
+ *
+ * An id that names no track never reaches here: `createPlaylist` refuses the
+ * whole call when one of its `songId`s is not a song, and refusing is the point
+ * — a playlist silently shorter than the request is a playlist the client
+ * cannot tell from one it sent correctly, and the missing song would only show
+ * up when somebody played the list through.
+ *
+ * The timestamps are the same instant: a playlist that was just made has not
+ * been changed since it was made.
+ */
+export function create(db, name, tracks, sourceFileId = null) {
+    const at = new Date().toISOString();
+    return withTransaction(db, () => {
+        const id = nextId(db);
+        db.prepare(`INSERT INTO playlist (id, name, comment, source_file_id, created_at, changed_at)
+       VALUES (?, ?, NULL, ?, ?, ?)`).run(id, name, sourceFileId, at, at);
+        writeEntries(db, id, tracks);
+        return written(db, id);
+    });
+}
+/**
+ * The row a write just left, read back.
+ *
+ * Every mutation that answers with the playlist answers with what is in the
+ * table rather than with what it meant to put there — so the counts, the
+ * timestamps and the entries in the answer are the ones a later `getPlaylist`
+ * would give, and cannot be a calculation that disagreed with the write.
+ */
+function written(db, id) {
+    const row = playlist(db, id);
+    if (row === undefined)
+        throw new Error(`playlist ${id} is not there after it was written`);
+    return row;
+}
+/**
+ * Rename a playlist and, when songs are given, make them its contents.
+ *
+ * This is `createPlaylist` handed an id that already exists, which the protocol
+ * makes the same call — see `api/playlist.ts` for why this server replaces the
+ * songs and for the one case where it does not.
+ *
+ * `tracks` is `undefined` when the client named no songs at all, and that is not
+ * the same as naming none: a call that renames a playlist carries no song list,
+ * and treating its silence as "empty the playlist" would throw away everything
+ * the listener put in it while answering `ok`. A client that means to empty a
+ * playlist says so — it sends no song it wants kept.
+ */
+export function replace(db, id, name, tracks) {
+    return withTransaction(db, () => {
+        db.prepare(`UPDATE playlist SET name = ?, ${TOUCH} WHERE id = ?`).run(name, new Date().toISOString(), id);
+        if (tracks !== undefined)
+            writeEntries(db, id, tracks);
+        return written(db, id);
+    });
+}
+export function edit(db, id, edit) {
+    const adds = edit.add !== undefined && edit.add.length > 0;
+    const removes = edit.remove !== undefined && edit.remove.length > 0;
+    const fields = edit.name !== undefined || edit.comment !== undefined || edit.public !== undefined;
+    if (!adds && !removes && !fields)
+        return;
+    withTransaction(db, () => {
+        let tracks = entriesOf(db, id);
+        if (removes) {
+            const doomed = new Set(edit.remove);
+            tracks = tracks.filter((_, position) => !doomed.has(position));
+        }
+        if (adds)
+            tracks = [...tracks, ...(edit.add ?? [])];
+        const sets = [];
+        const args = [];
+        if (edit.name !== undefined) {
+            sets.push('name = ?');
+            args.push(edit.name);
+        }
+        if (edit.comment !== undefined) {
+            sets.push('comment = ?');
+            args.push(edit.comment);
+        }
+        if (edit.public !== undefined) {
+            sets.push('public = ?');
+            args.push(edit.public ? 1 : 0);
+        }
+        sets.push(TOUCH);
+        args.push(new Date().toISOString(), id);
+        db.prepare(`UPDATE playlist SET ${sets.join(', ')} WHERE id = ?`).run(...args);
+        if (adds || removes)
+            writeEntries(db, id, tracks);
+    });
+}
+/** A playlist and its entries, gone. The songs themselves are untouched. */
+export function remove(db, id) {
+    db.prepare('DELETE FROM playlist WHERE id = ?').run(id);
+}
+/**
+ * The playlist a file asked for, if this server has imported it.
+ *
+ * How an import stays one playlist: the file is what the list *is*, so the row
+ * it produced is found by the file rather than by its name — a scan that reads
+ * the same file again updates that row instead of making a second list with the
+ * same name, and a third on the run after that.
+ */
+export function bySourceFile(db, fileId) {
+    return db
+        .prepare(`${PLAYLIST_SELECT} WHERE p.source_file_id = ? GROUP BY p.id`)
+        .get(fileId);
+}
+/** The playlist a file asked for, gone — the file stopped asking for one. */
+export function removeBySourceFile(db, fileId) {
+    db.prepare('DELETE FROM playlist WHERE source_file_id = ?').run(fileId);
+}