@neurowire/core 0.1.0 → 0.4.0

package/dist/index.d.ts

@@ -296,6 +296,44 @@ type Mesh = z.infer<typeof MeshSchema>;
 /** Validate an unknown value into a Mesh. Throws (ZodError) on invalid input. */
 declare function parseMesh(data: unknown): Mesh;
 
+/**
+ * Pure dedup helpers for watch-style polling. They compute a stable identity per
+ * entry and select the entries a caller has not seen yet. No I/O, no clock, no
+ * network: the seen-state lives entirely in the calling app layer.
+ */
+/** Stable identity for dedup: the entry id when present, else its link. */
+declare function entryKey(entry: NeurowireEntry): string;
+/**
+ * The feed's entries whose {@link entryKey} is not in `seen`, in original order.
+ * `seen` is any iterable of keys (an array, a Set, ...); it is read once.
+ */
+declare function newEntries(feed: NeurowireFeed, seen: Iterable<string>): NeurowireEntry[];
+
+/**
+ * Pure, deterministic entry filtering by field and pattern. A rule matches a
+ * single field (title, summary, source, author, tag) against a substring or a
+ * regular expression. `filterEntries` keeps entries that satisfy an include set
+ * and avoid an exclude set. No I/O, no clock, no DOM.
+ */
+type FilterField = 'title' | 'summary' | 'source' | 'author' | 'tag';
+interface FilterRule {
+    field: FilterField;
+    pattern: string;
+    regex?: boolean;
+}
+interface FilterSpec {
+    include?: FilterRule[];
+    exclude?: FilterRule[];
+}
+/** Does any of the entry's values for the rule's field match the pattern? */
+declare function matchRule(entry: NeurowireEntry, rule: FilterRule): boolean;
+/**
+ * Keep an entry iff it matches at least one include rule (or there are none)
+ * and matches none of the exclude rules. An empty spec returns the feed
+ * entries unchanged.
+ */
+declare function filterEntries(feed: NeurowireFeed, spec: FilterSpec): NeurowireFeed;
+
 /** One feed plus the source label its entries should carry in a merge. */
 interface MergePart {
     feed: NeurowireFeed;
@@ -317,6 +355,55 @@ interface MergeOptions {
  */
 declare function mergeFeeds(title: string, parts: MergePart[], options?: MergeOptions): NeurowireFeed;
 
+/**
+ * Pure, deterministic feed refinement: a time-window filter, a sort, and a
+ * limit. These operate on the canonical model and never touch the clock or the
+ * network themselves. Callers pass `now` (epoch ms) into `resolveWindow`, which
+ * keeps the whole module testable and side-effect free.
+ */
+type SortKey = 'date' | 'title' | 'source';
+type SortOrder = 'asc' | 'desc';
+interface SelectOptions {
+    /** Keep entries dated at or after this epoch-ms bound (inclusive). */
+    from?: number;
+    /** Keep entries dated at or before this epoch-ms bound (inclusive). */
+    to?: number;
+    sort?: SortKey;
+    order?: SortOrder;
+    /** Keep at most this many entries after filtering and sorting. */
+    limit?: number;
+}
+/** Parse a duration like "24h", "90m", or "7d" into milliseconds. */
+declare function parseDuration(value: string): number | undefined;
+interface WindowSpec {
+    /** Within this duration before now, e.g. "24h". */
+    since?: string;
+    /** Drop anything older than this duration, e.g. "7d". Same window as `since`. */
+    maxAge?: string;
+    /** Since midnight UTC today. */
+    today?: boolean;
+    /** Since midnight UTC of the current week (Monday). */
+    thisWeek?: boolean;
+    /** An explicit [start, end] pair of ISO dates (or anything Date.parse reads). */
+    between?: [string, string];
+}
+interface TimeWindow {
+    from?: number;
+    to?: number;
+}
+/**
+ * Turn a high-level window spec into concrete epoch-ms bounds, relative to
+ * `now`. Precedence when several are set: between > today > thisWeek > since/maxAge.
+ * Unparseable values yield an open-ended bound on that side.
+ */
+declare function resolveWindow(spec: WindowSpec, now: number): TimeWindow;
+/**
+ * Apply a date window, an optional sort, and an optional limit to a feed.
+ * Date sorts default to newest-first; title and source sorts default to A-Z.
+ * Entries without a parseable date are dropped only when a date bound is set.
+ */
+declare function selectEntries(feed: NeurowireFeed, opts: SelectOptions): NeurowireFeed;
+
 /** Serialize a feed to an Atom 1.0 document. */
 declare function toAtom(feed: NeurowireFeed): string;
 
@@ -385,4 +472,4 @@ declare function isFormat(value: string): value is Format;
 /** Serialize a feed to the requested format. */
 declare function serialize(feed: NeurowireFeed, format: Format): string;
 
-export { EXTENSIONS, EntrySchema, FORMATS, FeedSchema, type Format, GENERATOR, type JsonFeedDocument, MEDIA_TYPES, type MergeOptions, type MergePart, type Mesh, MeshSchema, type MeshSource, MeshSourceSchema, type NeurowireEntry, type NeurowireFeed, type NwfIssue, type NwfValidation, type Person, PersonSchema, fromNwf, isFormat, mergeFeeds, parseMesh, parseNeurowireFeed, serialize, toAtom, toJsonFeed, toJsonFeedObject, toMarkdown, toNwf, validateNwf };
+export { EXTENSIONS, EntrySchema, FORMATS, FeedSchema, type FilterField, type FilterRule, type FilterSpec, type Format, GENERATOR, type JsonFeedDocument, MEDIA_TYPES, type MergeOptions, type MergePart, type Mesh, MeshSchema, type MeshSource, MeshSourceSchema, type NeurowireEntry, type NeurowireFeed, type NwfIssue, type NwfValidation, type Person, PersonSchema, type SelectOptions, type SortKey, type SortOrder, type TimeWindow, type WindowSpec, entryKey, filterEntries, fromNwf, isFormat, matchRule, mergeFeeds, newEntries, parseDuration, parseMesh, parseNeurowireFeed, resolveWindow, selectEntries, serialize, toAtom, toJsonFeed, toJsonFeedObject, toMarkdown, toNwf, validateNwf };

package/dist/index.js

@@ -1,3 +1,48 @@
+// src/diff.ts
+function entryKey(entry) {
+  return entry.id || entry.link;
+}
+function newEntries(feed, seen) {
+  const known = new Set(seen);
+  return feed.entries.filter((entry) => !known.has(entryKey(entry)));
+}
+
+// src/filter.ts
+function fieldValues(entry, field) {
+  switch (field) {
+    case "title":
+      return [entry.title];
+    case "summary":
+      return [entry.summary ?? ""];
+    case "source":
+      return [entry.source?.name ?? ""];
+    case "author":
+      return [(entry.authors ?? []).map((a) => a.name).join(" ")];
+    case "tag":
+      return entry.tags ?? [];
+  }
+}
+function matchRule(entry, rule) {
+  const values = fieldValues(entry, rule.field);
+  if (rule.regex) {
+    const re = new RegExp(rule.pattern, "i");
+    return values.some((value) => re.test(value));
+  }
+  const needle = rule.pattern.toLowerCase();
+  return values.some((value) => value.toLowerCase().includes(needle));
+}
+function filterEntries(feed, spec) {
+  const include = spec.include ?? [];
+  const exclude = spec.exclude ?? [];
+  if (include.length === 0 && exclude.length === 0) return feed;
+  const kept = feed.entries.filter((entry) => {
+    if (include.length > 0 && !include.some((rule) => matchRule(entry, rule))) return false;
+    if (exclude.some((rule) => matchRule(entry, rule))) return false;
+    return true;
+  });
+  return { ...feed, entries: kept };
+}
+
 // src/model.ts
 import { z } from "zod";
 var PersonSchema = z.object({
@@ -83,6 +128,82 @@ function mergeFeeds(title, parts, options = {}) {
   };
 }
 
+// src/refine.ts
+var DAY = 864e5;
+var UNIT_MS = { m: 6e4, h: 36e5, d: 864e5 };
+function parseDuration(value) {
+  const match = /^(\d+)\s*([mhd])$/.exec(value.trim());
+  if (!match) return void 0;
+  return Number(match[1]) * UNIT_MS[match[2]];
+}
+function startOfUtcDay(now) {
+  return Math.floor(now / DAY) * DAY;
+}
+function startOfUtcWeek(now) {
+  const dayNumber = Math.floor(now / DAY);
+  const weekday = ((dayNumber % 7 + 3) % 7 + 7) % 7;
+  return (dayNumber - weekday) * DAY;
+}
+function resolveWindow(spec, now) {
+  if (spec.between) {
+    const from = Date.parse(spec.between[0]);
+    const to = Date.parse(spec.between[1]);
+    return {
+      from: Number.isNaN(from) ? void 0 : from,
+      to: Number.isNaN(to) ? void 0 : to
+    };
+  }
+  if (spec.today) return { from: startOfUtcDay(now) };
+  if (spec.thisWeek) return { from: startOfUtcWeek(now) };
+  const duration = spec.since ?? spec.maxAge;
+  if (duration !== void 0) {
+    const ms = parseDuration(duration);
+    return ms === void 0 ? {} : { from: now - ms };
+  }
+  return {};
+}
+function entryTime2(entry) {
+  return Date.parse(entry.published ?? entry.updated ?? "");
+}
+function compareByTime(a, b) {
+  const ta = entryTime2(a);
+  const tb = entryTime2(b);
+  const aMissing = Number.isNaN(ta);
+  const bMissing = Number.isNaN(tb);
+  if (aMissing && bMissing) return 0;
+  if (aMissing) return -1;
+  if (bMissing) return 1;
+  return ta - tb;
+}
+function compare(key, a, b) {
+  if (key === "title") return a.title.localeCompare(b.title);
+  if (key === "source") {
+    return (a.source?.name ?? "").localeCompare(b.source?.name ?? "") || compareByTime(a, b);
+  }
+  return compareByTime(a, b);
+}
+function selectEntries(feed, opts) {
+  const { from, to, sort, order, limit } = opts;
+  let entries = feed.entries;
+  if (from !== void 0 || to !== void 0) {
+    entries = entries.filter((entry) => {
+      const t = entryTime2(entry);
+      if (Number.isNaN(t)) return false;
+      if (from !== void 0 && t < from) return false;
+      if (to !== void 0 && t > to) return false;
+      return true;
+    });
+  }
+  if (sort) {
+    const direction = (order ?? (sort === "date" ? "desc" : "asc")) === "asc" ? 1 : -1;
+    entries = [...entries].sort((a, b) => direction * compare(sort, a, b));
+  }
+  if (limit !== void 0 && limit >= 0) {
+    entries = entries.slice(0, limit);
+  }
+  return { ...feed, entries };
+}
+
 // src/serialize/atom.ts
 var escapeText = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 var escapeAttr = (s) => escapeText(s).replace(/"/g, "&quot;");
@@ -579,11 +700,18 @@ export {
   MeshSchema,
   MeshSourceSchema,
   PersonSchema,
+  entryKey,
+  filterEntries,
   fromNwf,
   isFormat,
+  matchRule,
   mergeFeeds,
+  newEntries,
+  parseDuration,
   parseMesh,
   parseNeurowireFeed,
+  resolveWindow,
+  selectEntries,
   serialize,
   toAtom,
   toJsonFeed,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neurowire/core",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Canonical feed model and serializers (Atom, JSON Feed 1.1, Markdown, nwf) for Neurowire.",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,7 +38,7 @@
     "url": "https://github.com/starside-io/neurowire/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public"