@aspan-corporation/ac-shared 1.2.30 → 1.2.32

package/lib/utils/diary.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Diary entries are Markdown files stored in a dedicated diary bucket at keys
+ * `diary/YYYY/MM/YYYYMMDD.md`. They are indexed in the shared metadata table so
+ * they are searchable through the same interface as photos. Body text is made
+ * searchable by tokenising it into `ac:text:<word>` tags that ride the existing
+ * inverted-index search table.
+ */
+/** Key prefix for every diary object (and the `folder`/id namespace). */
+export declare const DIARY_PREFIX = "diary/";
+/** Marks a meta item as a diary entry (value "true"). */
+export declare const TAG_DIARY_ENTRY = "ac:diary:entry";
+/** Human title of the entry. */
+export declare const TAG_DIARY_TITLE = "ac:diary:title";
+/** Short body preview for card display (first ~160 chars, no markdown). */
+export declare const TAG_DIARY_PREVIEW = "ac:diary:preview";
+/** One per embedded photo: value is the referenced media key. */
+export declare const TAG_DIARY_PHOTO = "ac:diary:photo";
+/** Namespace for body word tokens: `ac:text:<word>`. */
+export declare const TEXT_TOKEN_PREFIX = "ac:text:";
+/** Max body characters surfaced in the preview tag. */
+export declare const DIARY_PREVIEW_LENGTH = 160;
+/** Upper bound on distinct word tokens written per entry (bounds item size). */
+export declare const MAX_TEXT_TOKENS = 400;
+/**
+ * Compute the diary object key for a date.
+ *   diaryKey(new Date())   → today's key in the caller's LOCAL timezone
+ *   diaryKey("2026-06-15") → "diary/2026/06/20260615.md" (literal Y-M-D)
+ *
+ * A `Date` is read with LOCAL components so "today" is the caller's wall-clock
+ * day (not the UTC day, which is a day ahead for users west of UTC in the
+ * evening). A `YYYY-MM-DD` string (e.g. from <input type="date">) is taken
+ * literally so the date round-trips exactly with no timezone shift.
+ */
+export declare const diaryKey: (date: Date | string) => string;
+/** True when an id/key is a diary entry object. */
+export declare const isDiaryKey: (key: string) => boolean;
+/**
+ * Parse the date out of a diary key (the inverse of `diaryKey`).
+ *   "diary/2026/06/20260615.md" → { year: 2026, month: 6, day: 15 }
+ * Returns undefined when the key isn't a recognised diary key.
+ */
+export declare const parseDiaryKeyDate: (key: string) => {
+    year: number;
+    month: number;
+    day: number;
+} | undefined;
+/**
+ * Tokenise diary markdown into a deduplicated set of searchable lowercase
+ * words. Strips markdown syntax (code fences, image/link targets, formatting),
+ * drops stop-words and tokens shorter than 2 chars, and caps the result at
+ * `MAX_TEXT_TOKENS` to bound the meta-item size. No stemming (exact-word match).
+ */
+export declare const tokenizeText: (markdown: string) => string[];
+/** Plain-text preview: strip markdown, collapse whitespace, truncate. */
+export declare const diaryPreview: (markdown: string) => string;
+/** Extract the media keys of photos embedded as `![alt](mediaKey)` in the body. */
+export declare const extractEmbeddedPhotoKeys: (markdown: string) => string[];

package/lib/utils/diary.js

@@ -0,0 +1,148 @@
+/**
+ * Diary entries are Markdown files stored in a dedicated diary bucket at keys
+ * `diary/YYYY/MM/YYYYMMDD.md`. They are indexed in the shared metadata table so
+ * they are searchable through the same interface as photos. Body text is made
+ * searchable by tokenising it into `ac:text:<word>` tags that ride the existing
+ * inverted-index search table.
+ */
+/** Key prefix for every diary object (and the `folder`/id namespace). */
+export const DIARY_PREFIX = "diary/";
+/** Marks a meta item as a diary entry (value "true"). */
+export const TAG_DIARY_ENTRY = "ac:diary:entry";
+/** Human title of the entry. */
+export const TAG_DIARY_TITLE = "ac:diary:title";
+/** Short body preview for card display (first ~160 chars, no markdown). */
+export const TAG_DIARY_PREVIEW = "ac:diary:preview";
+/** One per embedded photo: value is the referenced media key. */
+export const TAG_DIARY_PHOTO = "ac:diary:photo";
+/** Namespace for body word tokens: `ac:text:<word>`. */
+export const TEXT_TOKEN_PREFIX = "ac:text:";
+/** Max body characters surfaced in the preview tag. */
+export const DIARY_PREVIEW_LENGTH = 160;
+/** Upper bound on distinct word tokens written per entry (bounds item size). */
+export const MAX_TEXT_TOKENS = 400;
+const pad2 = (n) => String(n).padStart(2, "0");
+/**
+ * Compute the diary object key for a date.
+ *   diaryKey(new Date())   → today's key in the caller's LOCAL timezone
+ *   diaryKey("2026-06-15") → "diary/2026/06/20260615.md" (literal Y-M-D)
+ *
+ * A `Date` is read with LOCAL components so "today" is the caller's wall-clock
+ * day (not the UTC day, which is a day ahead for users west of UTC in the
+ * evening). A `YYYY-MM-DD` string (e.g. from <input type="date">) is taken
+ * literally so the date round-trips exactly with no timezone shift.
+ */
+export const diaryKey = (date) => {
+    let y;
+    let m;
+    let day;
+    if (typeof date === "string") {
+        const lit = /^(\d{4})-(\d{2})-(\d{2})/.exec(date);
+        if (lit) {
+            y = Number(lit[1]);
+            m = Number(lit[2]);
+            day = Number(lit[3]);
+        }
+        else {
+            const d = new Date(date);
+            if (isNaN(d.getTime()))
+                throw new Error(`diaryKey: invalid date "${date}"`);
+            y = d.getFullYear();
+            m = d.getMonth() + 1;
+            day = d.getDate();
+        }
+    }
+    else {
+        if (isNaN(date.getTime()))
+            throw new Error("diaryKey: invalid Date");
+        y = date.getFullYear();
+        m = date.getMonth() + 1;
+        day = date.getDate();
+    }
+    return `${DIARY_PREFIX}${y}/${pad2(m)}/${y}${pad2(m)}${pad2(day)}.md`;
+};
+/** True when an id/key is a diary entry object. */
+export const isDiaryKey = (key) => key.startsWith(DIARY_PREFIX) && key.endsWith(".md");
+/**
+ * Parse the date out of a diary key (the inverse of `diaryKey`).
+ *   "diary/2026/06/20260615.md" → { year: 2026, month: 6, day: 15 }
+ * Returns undefined when the key isn't a recognised diary key.
+ */
+export const parseDiaryKeyDate = (key) => {
+    const m = /diary\/(\d{4})\/(\d{2})\/(\d{4})(\d{2})(\d{2})\.md$/.exec(key);
+    if (!m)
+        return undefined;
+    return { year: Number(m[3]), month: Number(m[4]), day: Number(m[5]) };
+};
+// A small English stop-word set — high-frequency words that add noise and bloat
+// the index without improving recall for a personal diary.
+const STOP_WORDS = new Set([
+    "the", "and", "for", "are", "but", "not", "you", "all", "any", "can", "had",
+    "her", "was", "one", "our", "out", "day", "get", "has", "him", "his", "how",
+    "its", "may", "new", "now", "old", "see", "two", "way", "who", "did", "yes",
+    "his", "she", "they", "them", "this", "that", "with", "have", "from", "your",
+    "were", "been", "their", "what", "when", "then", "than", "into", "just",
+    "like", "over", "also", "back", "after", "would", "could", "there", "here",
+    "about", "which", "while", "these", "those", "where", "very", "much", "some",
+    "such", "only", "more", "most", "will", "well", "went", "going", "got",
+]);
+/**
+ * Tokenise diary markdown into a deduplicated set of searchable lowercase
+ * words. Strips markdown syntax (code fences, image/link targets, formatting),
+ * drops stop-words and tokens shorter than 2 chars, and caps the result at
+ * `MAX_TEXT_TOKENS` to bound the meta-item size. No stemming (exact-word match).
+ */
+export const tokenizeText = (markdown) => {
+    if (!markdown)
+        return [];
+    const stripped = markdown
+        // fenced + inline code
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`[^`]*`/g, " ")
+        // image / link targets: keep the visible text, drop the URL/key
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, " $1 ")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, " $1 ")
+        // leftover markdown punctuation
+        .replace(/[#>*_~\-]+/g, " ");
+    const seen = new Set();
+    for (const raw of stripped.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 2)
+            continue;
+        // Drop pure numbers (dates/counts add noise); keep alphanumerics like "v2".
+        if (/^\d+$/.test(raw))
+            continue;
+        if (STOP_WORDS.has(raw))
+            continue;
+        seen.add(raw);
+        if (seen.size >= MAX_TEXT_TOKENS)
+            break;
+    }
+    return [...seen];
+};
+/** Plain-text preview: strip markdown, collapse whitespace, truncate. */
+export const diaryPreview = (markdown) => {
+    const text = markdown
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`[^`]*`/g, " ")
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, " ")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, " $1 ")
+        .replace(/[#>*_~]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return text.length > DIARY_PREVIEW_LENGTH
+        ? text.slice(0, DIARY_PREVIEW_LENGTH).trimEnd() + "…"
+        : text;
+};
+/** Extract the media keys of photos embedded as `![alt](mediaKey)` in the body. */
+export const extractEmbeddedPhotoKeys = (markdown) => {
+    const keys = new Set();
+    const re = /!\[[^\]]*\]\(([^)]+)\)/g;
+    let m;
+    while ((m = re.exec(markdown)) !== null) {
+        const key = m[1].trim();
+        // Only treat library media keys as photo links (ignore external URLs).
+        if (key && !/^https?:\/\//i.test(key))
+            keys.add(key);
+    }
+    return [...keys];
+};

package/lib/utils/index.d.ts

@@ -4,3 +4,4 @@ export * from "./thumbsKey.js";
 export * from "./helpers.js";
 export * from "./processMeta.js";
 export * from "./parseFolderDate.js";
+export * from "./diary.js";

package/lib/utils/index.js

@@ -8,3 +8,4 @@ export * from "./thumbsKey.js";
 export * from "./helpers.js";
 export * from "./processMeta.js";
 export * from "./parseFolderDate.js";
+export * from "./diary.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspan-corporation/ac-shared",
-  "version": "1.2.30",
+  "version": "1.2.32",
   "description": "",
   "keywords": [],
   "exports": {
@@ -23,6 +23,10 @@
     "./utils/thumbsKey": {
       "types": "./lib/utils/thumbsKey.d.ts",
       "import": "./lib/utils/thumbsKey.js"
+    },
+    "./utils/diary": {
+      "types": "./lib/utils/diary.d.ts",
+      "import": "./lib/utils/diary.js"
     }
   },
   "author": "",