@jant/core 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/dist/{app-CFsmRVJN.js → app-BzH8jmh3.js} +1619 -500
  2. package/dist/client/.vite/manifest.json +2 -2
  3. package/dist/client/_assets/{client-DTLBOHqD.js → client-S8oryJ0m.js} +1 -1
  4. package/dist/client/_assets/{client-auth-D6Ix6SmE.js → client-auth-Ds9G0IgR.js} +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/node.js +2 -2
  7. package/package.json +1 -1
  8. package/src/__tests__/fixtures/releases/0.8.0/site-export/README.md +130 -0
  9. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/2thjq/_index.md +25 -0
  10. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/2u5e5/_index.md +35 -0
  11. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/41q27/0x4nv/index.md +18 -0
  12. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/41q27/_index.md +44 -0
  13. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/41q27/faqyt/index.md +30 -0
  14. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/41q27/the-potting-mix-guide-i-keep-rereading/index.md +20 -0
  15. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/5kayp/_index.md +23 -0
  16. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/5ynfs/_index.md +31 -0
  17. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/5ynfs/hu597/index.md +21 -0
  18. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/_index.md +5 -0
  19. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/a-night-heron-field-guide-for-my-walk-folder/_index.md +31 -0
  20. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/a-quiet-saturday-after-a-busy-week/_index.md +36 -0
  21. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/archive/_index.md +8 -0
  22. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/are-na-is-the-only-bookmark-pile-i-still-revisit/_index.md +30 -0
  23. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/bought-too-many-lemons-again/_index.md +37 -0
  24. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/city-walks/_index.md +12 -0
  25. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/cleanshot-for-screenshots-ocr-and-screen-recording-on-the-mac/_index.md +33 -0
  26. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/cleanshotmac-shang-de-jie-tu-ocr-lu-ping-gong-ju/_index.md +32 -0
  27. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/co344/_index.md +25 -0
  28. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/collections/_index.md +5 -0
  29. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/current-tea-rotation/_index.md +34 -0
  30. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/derek-sivers-still-writes-the-kind-of-internet-i-want-more-of/_index.md +30 -0
  31. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/desk-but-better/_index.md +25 -0
  32. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/e0kcg/_index.md +22 -0
  33. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/egi3c/_index.md +24 -0
  34. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/evf9j/_index.md +152 -0
  35. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/featured/_index.md +8 -0
  36. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-basho/_index.md +25 -0
  37. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-epictetus/_index.md +25 -0
  38. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-marcus-aurelius/_index.md +25 -0
  39. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-seneca/_index.md +26 -0
  40. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/from-thoreau/_index.md +25 -0
  41. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gkbvv/2cl6d/index.md +18 -0
  42. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gkbvv/3zqv7/index.md +30 -0
  43. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gkbvv/5oxsv/index.md +18 -0
  44. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gkbvv/_index.md +39 -0
  45. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/gwob9/_index.md +25 -0
  46. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/home-cooking/_index.md +12 -0
  47. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/hz729/_index.md +24 -0
  48. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/inaturalist-ai-zi-ran-she-qu/_index.md +44 -0
  49. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/j4v0q/_index.md +35 -0
  50. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k278t/_index.md +25 -0
  51. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k4eee/_index.md +22 -0
  52. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k5vh8/_index.md +32 -0
  53. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k5vh8/a-reading-log-idea-i-might-steal/index.md +20 -0
  54. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k5vh8/a83qu/index.md +18 -0
  55. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/k5vh8/from-seneca-5hibo/index.md +21 -0
  56. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/kan-qi-lai-bi-jiao-ku-de-gong-si-men/_index.md +41 -0
  57. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/l2m7y/_index.md +29 -0
  58. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/lan-ya-yao-kong-qi-chuang-shang-yue-du-de-fan-ye-shen-qi/_index.md +57 -0
  59. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/mynoise-for-rainy-afternoons/_index.md +30 -0
  60. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/n09le/_index.md +23 -0
  61. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/ni-fu-jin-de-wei-ji-bai-ke-tiao-mu/_index.md +42 -0
  62. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/nts-archives-are-good-cleaning-music/_index.md +30 -0
  63. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/qgfcu/_index.md +32 -0
  64. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/qgfcu/c91j0/index.md +18 -0
  65. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/qgfcu/qyucy/index.md +18 -0
  66. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/qgfcu/wsgck/index.md +18 -0
  67. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/rain-makes-my-neighborhood-look-better/_index.md +46 -0
  68. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/reading-notes/_index.md +12 -0
  69. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/s4r3e/_index.md +25 -0
  70. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/serious-eats-on-tomato-and-egg-soup/_index.md +30 -0
  71. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/te812/_index.md +44 -0
  72. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/te812/cxiu6/index.md +18 -0
  73. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/te812/t77ms/index.md +18 -0
  74. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/te812/the-soup-trick-i-always-forget/index.md +20 -0
  75. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/telk3/_index.md +30 -0
  76. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/telk3/from-thoreau-pawt2/index.md +21 -0
  77. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/the-five-minute-reset-is-still-the-best-habit-i-have/_index.md +36 -0
  78. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/the-hallway-light-took-12-minutes-and-3-months/_index.md +32 -0
  79. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/the-recurse-center-manual-is-weirdly-calming/_index.md +30 -0
  80. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/tiny-projects/_index.md +12 -0
  81. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/tong-wang-xing-fu-zhi-lu/_index.md +68 -0
  82. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/tou-ma-yan-jiang-ju-le-bu-chu-ti-yan/_index.md +62 -0
  83. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/useful-links/_index.md +12 -0
  84. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/weekend-notes/_index.md +12 -0
  85. package/src/__tests__/fixtures/releases/0.8.0/site-export/content/what-i-actually-use-my-notebook-for/_index.md +52 -0
  86. package/src/__tests__/fixtures/releases/0.8.0/site-export/data/jant.toml +124 -0
  87. package/src/__tests__/fixtures/releases/0.8.0/site-export/hugo.toml +45 -0
  88. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/_redirects +25 -0
  89. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/15d51730a4f7-med_01kn8jtq3penf98tfq4gzmh9g9.png +0 -0
  90. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jtx8qenf98tm9ahxr48sw.webp +0 -0
  91. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jv0jdenf98tp6qr9zgjjc.webp +0 -0
  92. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jv452enf98trbkwrvhvgd.webp +0 -0
  93. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jvb16enf98txp7p0pf5ge.webp +0 -0
  94. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jve5nenf98tzap11gpxzr.webp +0 -0
  95. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jvq58enf98v538w5vsqp4.webp +0 -0
  96. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jvsaeenf98v6ct4gjzppc.webp +0 -0
  97. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01kn8jw26cenf98vc7k0ppz5k8.webp +0 -0
  98. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m313q1hme4e8cmby77dn66yy.webp +0 -0
  99. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m313q2w7e4e8cmc20036yh66.webp +0 -0
  100. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m313q7d2e4e8cmdeqjmyafby.webp +0 -0
  101. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m313q887e4e8cmdjssych7yh.webp +0 -0
  102. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167jx2f6ct88pkz45j3ycp-poster.webp +0 -0
  103. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167jx2f6ct88pkz45j3ycp.mp4 +0 -0
  104. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167mbdf6ct88pr4ga1b9kf-poster.webp +0 -0
  105. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167mbdf6ct88pr4ga1b9kf.mp4 +0 -0
  106. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167nsvf6ct88q1anhz4svb-poster.webp +0 -0
  107. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167nsvf6ct88q1anhz4svb.mp4 +0 -0
  108. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167qaxf6ct88qfndwzxx83-poster.webp +0 -0
  109. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167qaxf6ct88qfndwzxx83.mp4 +0 -0
  110. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167sm0f6ct88qw5brtsgcw.webp +0 -0
  111. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167tf8f6ct88r169s51j49.webp +0 -0
  112. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167vaaf6ct88rbx5ztenwb.webp +0 -0
  113. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167w51f6ct88rp19pybkw1.webp +0 -0
  114. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167x0nf6ct88rzajb84tw3.webp +0 -0
  115. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167xxbf6ct88s5t2300bjk.webp +0 -0
  116. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167yq5f6ct88s9pjwt5fxg.webp +0 -0
  117. package/src/__tests__/fixtures/releases/0.8.0/site-export/static/media/med_01m3167zg4f6ct88sge8jp28ja.webp +0 -0
  118. package/src/__tests__/fixtures/releases/0.8.0/site-export/themes/jant/static/apple-touch-icon.png +0 -0
  119. package/src/__tests__/fixtures/releases/0.8.0/site-export/themes/jant/static/custom.css +0 -0
  120. package/src/__tests__/fixtures/releases/0.8.0/site-export/themes/jant/static/favicon.ico +0 -0
  121. package/src/__tests__/fixtures/releases/0.8.0/site-export/wrangler.jsonc +24 -0
  122. package/src/__tests__/fixtures/releases/0.8.0/snapshot/db.sql +322 -0
  123. package/src/__tests__/fixtures/releases/0.8.0/snapshot/meta.json +11 -0
  124. package/src/__tests__/helpers/cursor-walk.ts +82 -0
  125. package/src/__tests__/release-fixtures.test.ts +6 -2
  126. package/src/app.tsx +4 -0
  127. package/src/lib/__tests__/post-list-cursor.test.ts +105 -0
  128. package/src/lib/__tests__/thread-fold.test.ts +43 -0
  129. package/src/lib/__tests__/timeline.test.ts +14 -14
  130. package/src/lib/api-posts.ts +110 -2
  131. package/src/lib/api-public-posts.ts +263 -0
  132. package/src/lib/api-threads.ts +207 -0
  133. package/src/lib/post-list-cursor.ts +211 -0
  134. package/src/lib/thread-fold.ts +83 -41
  135. package/src/lib/thread-query.ts +143 -0
  136. package/src/middleware/cors.ts +8 -1
  137. package/src/middleware/deprecation.ts +48 -0
  138. package/src/routes/api/__tests__/mcp.test.ts +147 -0
  139. package/src/routes/api/__tests__/posts.test.ts +157 -0
  140. package/src/routes/api/__tests__/public-access.test.ts +5 -0
  141. package/src/routes/api/__tests__/threads.test.ts +115 -0
  142. package/src/routes/api/posts.ts +19 -112
  143. package/src/routes/api/public/__tests__/archive.test.ts +261 -0
  144. package/src/routes/api/public/__tests__/posts.test.ts +344 -19
  145. package/src/routes/api/public/__tests__/threads.test.ts +363 -0
  146. package/src/routes/api/public/archive.ts +82 -79
  147. package/src/routes/api/public/posts.ts +97 -299
  148. package/src/routes/api/public/threads.ts +141 -0
  149. package/src/routes/api/threads.ts +128 -0
  150. package/src/services/__tests__/post.test.ts +342 -36
  151. package/src/services/__tests__/thread.test.ts +495 -0
  152. package/src/services/index.ts +4 -0
  153. package/src/services/mcp.ts +213 -63
  154. package/src/services/post.ts +734 -361
  155. package/src/services/thread.ts +392 -0
  156. package/src/types/constants.ts +25 -0
  157. package/src/ui/feed/ThreadPreview.tsx +9 -14
  158. package/src/ui/feed/__tests__/thread-preview.test.ts +18 -22
  159. package/src/ui/feed/thread-preview-state.ts +0 -35
  160. package/src/ui/shared/Pagination.tsx +1 -1
@@ -0,0 +1,392 @@
1
+ /**
2
+ * Thread Service
3
+ *
4
+ * Threads as a resource of their own: a list of Thread roots in one of the
5
+ * orders the site shows, each with its Post count and, on request, the fold the
6
+ * homepage draws; one Thread by any of its Posts; and a Thread's Posts in Thread
7
+ * order.
8
+ *
9
+ * Every read goes through `PostService`. What lives here is the choice of read:
10
+ * which order a request names, when a collection's own order and pins apply,
11
+ * and what a reader may see as opposed to the author.
12
+ */
13
+
14
+ import {
15
+ resolveCollectionSortOrder,
16
+ supportsCollectionRatingSort,
17
+ } from "../lib/collection-sort.js";
18
+ import { ValidationError } from "../lib/errors.js";
19
+ import {
20
+ toPostFilters,
21
+ type PostFilterSelection,
22
+ } from "../lib/filter-dimensions.js";
23
+ import { foldReplyWindows, type ThreadFold } from "../lib/thread-fold.js";
24
+ import type {
25
+ CollectionSortOrder,
26
+ Post,
27
+ Status,
28
+ ThreadSort,
29
+ } from "../types.js";
30
+ import type { CollectionService } from "./collection.js";
31
+ import type {
32
+ PostFilters,
33
+ PostListPageOptions,
34
+ PostListPage,
35
+ PostService,
36
+ ThreadRootPageOptions,
37
+ } from "./post.js";
38
+
39
+ /**
40
+ * Who is asking. A reader sees what the site shows anyone: published Threads
41
+ * that aren't private. The author sees every Thread.
42
+ */
43
+ export type ThreadAudience = "reader" | "author";
44
+
45
+ /** What a Thread list is asked for. */
46
+ export interface ThreadListQuery {
47
+ audience: ThreadAudience;
48
+ /** The author's status filter; a reader always sees `published`. */
49
+ status?: Status;
50
+ /** Filter dimensions, with collection slugs already resolved to IDs. */
51
+ selection: PostFilterSelection;
52
+ /**
53
+ * A reader's list leaves out Threads hidden from Latest, as the homepage
54
+ * does, unless this is set. A visibility in `selection` is the whole
55
+ * visibility filter and overrides both.
56
+ */
57
+ includeHidden?: boolean;
58
+ /** One content language, as a canonical BCP 47 tag. */
59
+ lang?: string;
60
+ /** Defaults to `activity`, or a named collection's own order. */
61
+ sort?: ThreadSort;
62
+ /** Attach the homepage fold to each Thread. */
63
+ fold?: boolean;
64
+ }
65
+
66
+ /** One Thread, as a list or a lookup returns it. */
67
+ export interface ThreadSummary {
68
+ root: Post;
69
+ /** Published Posts in the Thread, the root included. */
70
+ postCount: number;
71
+ /** Present when asked for; null when the Thread has no published reply. */
72
+ fold?: ThreadFold<Post> | null;
73
+ }
74
+
75
+ /** One page of Threads, and the opaque cursor that continues it. */
76
+ export interface ThreadListPage {
77
+ threads: ThreadSummary[];
78
+ nextCursor: string | null;
79
+ }
80
+
81
+ /** How a Thread is named: by a Post ID, or by a Post's slug. */
82
+ export type ThreadRef = { id: string } | { slug: string };
83
+
84
+ export interface ThreadService {
85
+ /**
86
+ * One page of Thread roots, in the order `query.sort` names.
87
+ *
88
+ * Without a `sort`, a single named collection lists in its own configured
89
+ * order and an aggregate of several in activity order; `activity`,
90
+ * `oldest`, and `rating` on a named collection also use the collection's
91
+ * pins, as its page does. `published` and `updated` treat a collection as a
92
+ * plain filter, as the archive does.
93
+ *
94
+ * @param query - What to list, for whom, and in which order
95
+ * @param page - The previous page's `nextCursor`, and the page size
96
+ * @returns The page's Threads and the cursor after them
97
+ * @throws {ValidationError} When the cursor can't be resumed, or when
98
+ * `visibility` is `featured` and `sort` names anything but `published`
99
+ * @example
100
+ * ```ts
101
+ * const page = await threads.listThreads(
102
+ * { audience: "reader", selection: {}, fold: true },
103
+ * { limit: 20 },
104
+ * );
105
+ * ```
106
+ */
107
+ listThreads(
108
+ query: ThreadListQuery,
109
+ page: PostListPageOptions,
110
+ ): Promise<ThreadListPage>;
111
+ /**
112
+ * The root of the Thread a Post belongs to, when `audience` may see it.
113
+ *
114
+ * A reader is answered only for a published Post in a published Thread that
115
+ * isn't private; a Thread hidden from Latest is still found.
116
+ *
117
+ * @param ref - Any Post in the Thread, by ID or by slug
118
+ * @param audience - Who is asking
119
+ * @returns The Thread's root, or null when there is none to show
120
+ * @example
121
+ * const root = await threads.findRoot({ slug: "a-reply" }, "reader");
122
+ */
123
+ findRoot(ref: ThreadRef, audience: ThreadAudience): Promise<Post | null>;
124
+ /**
125
+ * Post counts, and the fold on request, for Thread roots already in hand.
126
+ *
127
+ * @param roots - Thread roots, in the order to return them
128
+ * @param options - `fold` attaches the homepage fold
129
+ * @returns One summary per root, in the same order
130
+ * @example
131
+ * const [summary] = await threads.summarize([root], { fold: true });
132
+ */
133
+ summarize(
134
+ roots: Post[],
135
+ options: { fold?: boolean },
136
+ ): Promise<ThreadSummary[]>;
137
+ /**
138
+ * One page of a Thread's Posts, in Thread order. A reader gets published
139
+ * Posts only; the author's `status` defaults to `published`.
140
+ *
141
+ * @param rootId - The Thread root's ID, as {@link findRoot} returned it
142
+ * @param query - Who is asking, and the author's status filter
143
+ * @param page - The previous page's `nextCursor` or a Post ID, and the size
144
+ * @returns The page's Posts and the cursor after them
145
+ * @example
146
+ * await threads.listPosts(root.id, { audience: "reader" }, { limit: 100 });
147
+ */
148
+ listPosts(
149
+ rootId: string,
150
+ query: { audience: ThreadAudience; status?: Status },
151
+ page: PostListPageOptions,
152
+ ): Promise<PostListPage>;
153
+ }
154
+
155
+ const FEATURED_SORT_MESSAGE =
156
+ "Featured posts are listed newest-published first. Leave sort out, or pass sort=published.";
157
+
158
+ /**
159
+ * How a plain Thread list orders each `ThreadSort`, as `PostFilters` fields.
160
+ * Only `activity`, the homepage's order, puts pinned Threads first.
161
+ */
162
+ function toListOrder(
163
+ sort: ThreadSort,
164
+ ): Pick<PostFilters, "sortBy" | "sortOrder" | "ignorePinnedSort"> {
165
+ switch (sort) {
166
+ case "activity":
167
+ return { sortBy: "activity", sortOrder: "newest" };
168
+ case "published":
169
+ return {
170
+ sortBy: "published",
171
+ sortOrder: "newest",
172
+ ignorePinnedSort: true,
173
+ };
174
+ case "updated":
175
+ return {
176
+ sortBy: "thread_updated",
177
+ sortOrder: "newest",
178
+ ignorePinnedSort: true,
179
+ };
180
+ case "oldest":
181
+ return {
182
+ sortBy: "published",
183
+ sortOrder: "oldest",
184
+ ignorePinnedSort: true,
185
+ };
186
+ case "rating":
187
+ return {
188
+ sortBy: "activity",
189
+ sortOrder: "rating_desc",
190
+ ignorePinnedSort: true,
191
+ };
192
+ }
193
+ }
194
+
195
+ /**
196
+ * The collection order a `ThreadSort` names, or null for the two that read a
197
+ * collection as a plain filter.
198
+ */
199
+ function toCollectionOrder(sort: ThreadSort): CollectionSortOrder | null {
200
+ switch (sort) {
201
+ case "activity":
202
+ return "newest";
203
+ case "oldest":
204
+ return "oldest";
205
+ case "rating":
206
+ return "rating_desc";
207
+ case "published":
208
+ case "updated":
209
+ return null;
210
+ }
211
+ }
212
+
213
+ /**
214
+ * Create the Thread service.
215
+ *
216
+ * @param deps - The Post and collection services it reads through
217
+ * @returns The Thread service
218
+ * @example
219
+ * const threads = createThreadService({ posts, collections });
220
+ */
221
+ export function createThreadService(deps: {
222
+ posts: PostService;
223
+ collections: CollectionService;
224
+ }): ThreadService {
225
+ const { posts, collections } = deps;
226
+
227
+ /**
228
+ * The order a collection's page would use: its configured order when it is
229
+ * the only one named, activity for several. A rating order with fewer than
230
+ * two rated Threads falls back, as the page does — for the default only; a
231
+ * caller who asks for `rating` gets it.
232
+ */
233
+ async function resolveDefaultCollectionOrder(
234
+ collectionIds: readonly string[],
235
+ options: ThreadRootPageOptions,
236
+ ): Promise<CollectionSortOrder> {
237
+ const [onlyId, ...others] = collectionIds;
238
+ if (!onlyId || others.length > 0) return "newest";
239
+
240
+ const collection = await collections.getById(onlyId);
241
+ if (!collection) return "newest";
242
+
243
+ const ratedThreadCount =
244
+ await posts.countCollectionThreadRootsUpToForCollections(
245
+ [onlyId],
246
+ { ...options, hasRating: true },
247
+ 2,
248
+ );
249
+ return resolveCollectionSortOrder(
250
+ undefined,
251
+ collection.sortOrder,
252
+ supportsCollectionRatingSort(ratedThreadCount),
253
+ );
254
+ }
255
+
256
+ const service: ThreadService = {
257
+ async listThreads(query, page) {
258
+ const reader = query.audience === "reader";
259
+ const { selection } = query;
260
+ const visibility = selection.visibility;
261
+ if (reader && visibility === "private") {
262
+ throw new ValidationError("Private posts aren't listed here.");
263
+ }
264
+ if (
265
+ visibility === "featured" &&
266
+ query.sort !== undefined &&
267
+ query.sort !== "published"
268
+ ) {
269
+ throw new ValidationError(FEATURED_SORT_MESSAGE);
270
+ }
271
+
272
+ const base = {
273
+ status: reader ? ("published" as const) : (query.status ?? "published"),
274
+ excludePrivate: reader,
275
+ excludeLatestHidden:
276
+ reader && visibility === undefined && !query.includeHidden,
277
+ lang: query.lang,
278
+ };
279
+
280
+ const collectionIds = selection.collection;
281
+ if (collectionIds && visibility !== "featured") {
282
+ // Membership is the collection query's own; the other dimensions
283
+ // narrow which roots it may return.
284
+ const { collection: _named, ...rootSelection } = selection;
285
+ const options: ThreadRootPageOptions = {
286
+ ...base,
287
+ rootFilters: toPostFilters(rootSelection, { yearAxis: "published" }),
288
+ };
289
+ const collectionOrder =
290
+ query.sort === undefined
291
+ ? await resolveDefaultCollectionOrder(collectionIds, options)
292
+ : toCollectionOrder(query.sort);
293
+
294
+ if (collectionOrder) {
295
+ const result = await posts.listCollectionThreadRootPage(
296
+ [...collectionIds],
297
+ { ...options, sortOrder: collectionOrder },
298
+ page,
299
+ );
300
+ return {
301
+ threads: await service.summarize(result.posts, query),
302
+ nextCursor: result.nextCursor,
303
+ };
304
+ }
305
+ }
306
+
307
+ const result = await posts.listPage(
308
+ {
309
+ ...base,
310
+ excludeReplies: true,
311
+ // Membership never depends on presentation: the year reads the
312
+ // publication date whatever the order.
313
+ ...toPostFilters(selection, { yearAxis: "published" }),
314
+ ...(visibility === "featured"
315
+ ? toListOrder("published")
316
+ : toListOrder(query.sort ?? "activity")),
317
+ },
318
+ page,
319
+ );
320
+ return {
321
+ threads: await service.summarize(result.posts, query),
322
+ nextCursor: result.nextCursor,
323
+ };
324
+ },
325
+
326
+ async findRoot(ref, audience) {
327
+ const post =
328
+ "id" in ref
329
+ ? await posts.getById(ref.id)
330
+ : await posts.getBySlug(ref.slug);
331
+ if (!post) return null;
332
+ if (audience === "reader" && post.status !== "published") return null;
333
+
334
+ const root =
335
+ post.threadId === post.id ? post : await posts.getById(post.threadId);
336
+ if (!root) return null;
337
+ if (
338
+ audience === "reader" &&
339
+ (root.status !== "published" || root.visibility === "private")
340
+ ) {
341
+ return null;
342
+ }
343
+ return root;
344
+ },
345
+
346
+ async summarize(roots, options) {
347
+ if (roots.length === 0) return [];
348
+ const rootIds = roots.map((root) => root.id);
349
+ const [counts, contexts] = await Promise.all([
350
+ posts.countThreadPosts(rootIds),
351
+ options.fold
352
+ ? posts.getThreadTimelineContext(rootIds)
353
+ : Promise.resolve(null),
354
+ ]);
355
+
356
+ return roots.map((root) => {
357
+ const summary: ThreadSummary = {
358
+ root,
359
+ postCount: counts.get(root.id) ?? 0,
360
+ };
361
+ if (contexts) {
362
+ const context = contexts.get(root.id);
363
+ summary.fold = context
364
+ ? foldReplyWindows({
365
+ leadingReplies: context.leadingReplies,
366
+ trailingReplies: context.trailingReplies,
367
+ latestReply: context.latestReply,
368
+ nextReply: context.firstHiddenReply,
369
+ totalReplyCount: context.totalReplyCount,
370
+ })
371
+ : null;
372
+ }
373
+ return summary;
374
+ });
375
+ },
376
+
377
+ async listPosts(rootId, query, page) {
378
+ return posts.listThreadPostsPage(
379
+ rootId,
380
+ {
381
+ status:
382
+ query.audience === "reader"
383
+ ? "published"
384
+ : (query.status ?? "published"),
385
+ },
386
+ page,
387
+ );
388
+ },
389
+ };
390
+
391
+ return service;
392
+ }
@@ -103,6 +103,31 @@ export type CollectionSortOrder = SortOrder;
103
103
  export const SMART_COLLECTION_SORT_ORDERS = COLLECTION_SORT_ORDERS;
104
104
  export type SmartCollectionSortOrder = CollectionSortOrder;
105
105
 
106
+ /**
107
+ * How the Threads API orders a list of Threads — each value one the site
108
+ * already shows somewhere, named for the axis it reads:
109
+ *
110
+ * - `activity`: the homepage, and a collection's `newest`. A Thread moves up
111
+ * when it gains an announced post.
112
+ * - `published`: the archive's default. Newest root publication first; a reply
113
+ * never moves a Thread, so this is the order to walk a whole site in.
114
+ * - `updated`: the archive's `?sort=updated`. Like `activity`, but a quiet
115
+ * reply counts too.
116
+ * - `oldest`: a collection's `oldest`. Oldest root publication first.
117
+ * - `rating`: a collection's `rating_desc`. Highest rating first, then activity.
118
+ *
119
+ * Not `SORT_ORDERS`: `newest` means activity on a collection and would read as
120
+ * publication here.
121
+ */
122
+ export const THREAD_SORTS = [
123
+ "activity",
124
+ "published",
125
+ "updated",
126
+ "oldest",
127
+ "rating",
128
+ ] as const;
129
+ export type ThreadSort = (typeof THREAD_SORTS)[number];
130
+
106
131
  export const NAV_ITEM_TYPES = [
107
132
  "link",
108
133
  "system",
@@ -11,10 +11,8 @@ import { useLingui } from "../../i18n/context.js";
11
11
  import type { ThreadPreviewProps } from "../../types.js";
12
12
  import { TimelineItem } from "./TimelineItem.js";
13
13
  import { TimelineItemFromPost } from "./TimelineItem.js";
14
- import {
15
- getThreadPreviewState,
16
- threadContextAssumesOverflow,
17
- } from "./thread-preview-state.js";
14
+ import { foldReplyWindows } from "../../lib/thread-fold.js";
15
+ import { threadContextAssumesOverflow } from "./thread-preview-state.js";
18
16
 
19
17
  const ROOT_CONTEXT_DISPLAY = {
20
18
  footer: {
@@ -40,12 +38,16 @@ export const ThreadPreview: FC<ThreadPreviewProps> = ({
40
38
  totalReplyCount,
41
39
  }) => {
42
40
  const { i18n } = useLingui();
43
- const { hiddenCount } = getThreadPreviewState({
41
+ // The gap's target arrives resolved as `gapHref`, so the fold is asked only
42
+ // what it shows and how much it hides.
43
+ const fold = foldReplyWindows({
44
44
  leadingReplies,
45
45
  trailingReplies,
46
46
  latestReply,
47
+ nextReply: null,
47
48
  totalReplyCount,
48
49
  });
50
+ const hiddenCount = fold.hiddenCount;
49
51
  const assumeOverflow = threadContextAssumesOverflow({
50
52
  rootPost,
51
53
  totalReplyCount,
@@ -73,15 +75,8 @@ export const ThreadPreview: FC<ThreadPreviewProps> = ({
73
75
  "@context: Collapse expanded thread ancestor context in the feed",
74
76
  }),
75
77
  );
76
- const visibleReplyIds = new Set([latestReply.id]);
77
- const dedupeReplies = (replies: typeof leadingReplies) =>
78
- replies.filter((reply) => {
79
- if (visibleReplyIds.has(reply.id)) return false;
80
- visibleReplyIds.add(reply.id);
81
- return true;
82
- });
83
- const renderedLeadingReplies = dedupeReplies(leadingReplies);
84
- const renderedTrailingReplies = dedupeReplies(trailingReplies);
78
+ const renderedLeadingReplies = fold.leadingReplies;
79
+ const renderedTrailingReplies = fold.trailingReplies;
85
80
  // The gap opens the first post it hides — the rule in `lib/thread-fold.ts`,
86
81
  // which the feed follows too. The fallback only covers a gap target that
87
82
  // went unpublished between the count and the fetch.
@@ -7,10 +7,8 @@ import { createI18n } from "../../../i18n/i18n.js";
7
7
  import type { PostView, TimelineItemView } from "../../../types.js";
8
8
  import { CuratedThreadPreview } from "../CuratedThreadPreview.js";
9
9
  import { ThreadPreview } from "../ThreadPreview.js";
10
- import {
11
- getThreadPreviewState,
12
- threadContextAssumesOverflow,
13
- } from "../thread-preview-state.js";
10
+ import { foldReplyWindows } from "../../../lib/thread-fold.js";
11
+ import { threadContextAssumesOverflow } from "../thread-preview-state.js";
14
12
 
15
13
  function createPostView(overrides: Partial<PostView> = {}): PostView {
16
14
  return {
@@ -57,7 +55,7 @@ function toggleTag(html: string): string {
57
55
  );
58
56
  }
59
57
 
60
- describe("getThreadPreviewState", () => {
58
+ describe("thread preview fold", () => {
61
59
  it("has no hidden posts for a 2-post thread", () => {
62
60
  const latestReply = createPostView({
63
61
  id: "post-2",
@@ -65,16 +63,16 @@ describe("getThreadPreviewState", () => {
65
63
  slug: "post-2",
66
64
  });
67
65
 
68
- expect(
69
- getThreadPreviewState({
70
- leadingReplies: [latestReply],
71
- trailingReplies: [],
72
- latestReply,
73
- totalReplyCount: 1,
74
- }),
75
- ).toEqual({
76
- hiddenCount: 0,
66
+ const fold = foldReplyWindows({
67
+ leadingReplies: [latestReply],
68
+ trailingReplies: [],
69
+ latestReply,
70
+ nextReply: null,
71
+ totalReplyCount: 1,
77
72
  });
73
+ expect(fold.hiddenCount).toBe(0);
74
+ // The only reply is the hero, so the leading window gives it up.
75
+ expect(fold.leadingReplies).toEqual([]);
78
76
  });
79
77
 
80
78
  it("has no hidden posts for a 6-post thread when all slots are visible", () => {
@@ -105,15 +103,14 @@ describe("getThreadPreviewState", () => {
105
103
  });
106
104
 
107
105
  expect(
108
- getThreadPreviewState({
106
+ foldReplyWindows({
109
107
  leadingReplies: [firstReply, secondReply],
110
108
  trailingReplies: [antepenultimateReply, penultimateReply],
111
109
  latestReply,
110
+ nextReply: antepenultimateReply,
112
111
  totalReplyCount: 5,
113
112
  }),
114
- ).toEqual({
115
- hiddenCount: 0,
116
- });
113
+ ).toMatchObject({ hiddenCount: 0, firstHiddenReply: null });
117
114
  });
118
115
 
119
116
  it("counts hidden posts for longer threads after deduping visible slots", () => {
@@ -144,15 +141,14 @@ describe("getThreadPreviewState", () => {
144
141
  });
145
142
 
146
143
  expect(
147
- getThreadPreviewState({
144
+ foldReplyWindows({
148
145
  leadingReplies: [firstReply, secondReply],
149
146
  trailingReplies: [antepenultimateReply, penultimateReply],
150
147
  latestReply,
148
+ nextReply: createPostView({ id: "post-4" }),
151
149
  totalReplyCount: 8,
152
150
  }),
153
- ).toEqual({
154
- hiddenCount: 3,
155
- });
151
+ ).toMatchObject({ hiddenCount: 3, firstHiddenReply: { id: "post-4" } });
156
152
  });
157
153
 
158
154
  it("keeps thread preview items shrinkable within the grid track", () => {
@@ -1,39 +1,4 @@
1
1
  import type { PostView } from "../../types.js";
2
- import { getThreadHiddenCount } from "../../lib/thread-fold.js";
3
-
4
- /**
5
- * What the preview needs to know about its own fold.
6
- *
7
- * The count itself lives in `lib/thread-fold.ts`, where the feed reads it too —
8
- * a card and a feed entry that disagreed about how many posts are hidden would
9
- * be describing different threads.
10
- *
11
- * @param selection - The replies this preview shows, and the thread's total
12
- * @returns The hidden-post count the gap link announces
13
- * @example
14
- * getThreadPreviewState({ leadingReplies, trailingReplies, latestReply,
15
- * totalReplyCount: 8 }); // { hiddenCount: 3 }
16
- */
17
- export function getThreadPreviewState({
18
- leadingReplies,
19
- trailingReplies,
20
- latestReply,
21
- totalReplyCount,
22
- }: {
23
- leadingReplies: PostView[];
24
- trailingReplies: PostView[];
25
- latestReply: PostView;
26
- totalReplyCount: number;
27
- }) {
28
- return {
29
- hiddenCount: getThreadHiddenCount({
30
- leadingReplies,
31
- trailingReplies,
32
- latestReply,
33
- totalReplyCount,
34
- }),
35
- };
36
- }
37
2
 
38
3
  /**
39
4
  * A lone root post shorter than this (plain-text code points) comfortably
@@ -15,7 +15,7 @@ export interface PaginationProps {
15
15
  baseUrl: string;
16
16
  /** Whether there are more items after the current page */
17
17
  hasMore: boolean;
18
- /** Cursor for the next page (typically the last item's ID) */
18
+ /** Cursor for the next page, as the list returned it. Opaque; never built from an item's ID. */
19
19
  nextCursor?: number | string;
20
20
  /** Cursor for the previous page */
21
21
  prevCursor?: number | string;