inkwire-receiver-core 0.1.1 → 1.0.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.
- package/README.md +135 -16
- package/dist/auth.d.ts +18 -1
- package/dist/auth.js +31 -5
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +13 -2
- package/dist/files.d.ts +33 -0
- package/dist/files.js +210 -0
- package/dist/handle.d.ts +135 -10
- package/dist/handle.js +483 -46
- package/dist/index.d.ts +18 -5
- package/dist/index.js +11 -4
- package/dist/list.d.ts +19 -0
- package/dist/list.js +66 -0
- package/dist/lock.d.ts +6 -0
- package/dist/lock.js +17 -0
- package/dist/media-meta.d.ts +22 -0
- package/dist/media-meta.js +64 -0
- package/dist/media.d.ts +20 -0
- package/dist/media.js +125 -0
- package/dist/render.d.ts +18 -0
- package/dist/render.js +53 -4
- package/dist/schema.d.ts +239 -6
- package/dist/schema.js +89 -6
- package/dist/seo.d.ts +9 -0
- package/dist/seo.js +39 -0
- package/dist/store.d.ts +102 -32
- package/dist/store.js +1 -18
- package/dist/stores/file.d.ts +67 -0
- package/dist/stores/file.js +227 -0
- package/dist/stores/github.d.ts +94 -0
- package/dist/stores/github.js +334 -0
- package/dist/stores/memory.d.ts +27 -0
- package/dist/stores/memory.js +65 -0
- package/dist/testing.d.ts +49 -0
- package/dist/testing.js +223 -0
- package/package.json +47 -9
- package/dist/__tests__/handle.test.d.ts +0 -1
- package/dist/__tests__/handle.test.js +0 -56
- package/dist/__tests__/render.test.d.ts +0 -1
- package/dist/__tests__/render.test.js +0 -17
package/dist/schema.js
CHANGED
|
@@ -1,15 +1,98 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
|
|
3
|
-
|
|
2
|
+
// Mirrors schema/inkwire-content.schema.json (create) and schema/inkwire-patch.schema.json (patch).
|
|
3
|
+
// The JSON schemas are authoritative where they disagree with this file.
|
|
4
|
+
const httpUrl = z
|
|
5
|
+
.string()
|
|
6
|
+
.url()
|
|
7
|
+
.refine((u) => /^https?:\/\//.test(u), { message: "must be an http(s) URL" });
|
|
8
|
+
const kind = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/);
|
|
9
|
+
const slug = z.string().max(255).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
|
|
10
|
+
const publishedAt = z.string().datetime({ offset: true });
|
|
11
|
+
const term = z.string().min(1).max(64);
|
|
12
|
+
const jsonLd = z
|
|
13
|
+
.string()
|
|
14
|
+
.min(2)
|
|
15
|
+
.max(20000)
|
|
16
|
+
.refine((v) => {
|
|
17
|
+
try {
|
|
18
|
+
const parsed = JSON.parse(v);
|
|
19
|
+
const isObject = (x) => !!x && typeof x === "object" && !Array.isArray(x);
|
|
20
|
+
return Array.isArray(parsed) ? parsed.length > 0 && parsed.every(isObject) : isObject(parsed);
|
|
21
|
+
}
|
|
22
|
+
catch {
|
|
23
|
+
return false;
|
|
24
|
+
}
|
|
25
|
+
}, { message: "must be one JSON object, or an array of objects, as a string" });
|
|
26
|
+
const author = z
|
|
27
|
+
.object({ name: z.string().optional(), email: z.string().email().optional() })
|
|
28
|
+
.strict();
|
|
29
|
+
export const ContentInput = z
|
|
30
|
+
.object({
|
|
4
31
|
external_id: z.string().min(1).max(255),
|
|
5
32
|
title: z.string().min(1).max(512),
|
|
6
33
|
markdown: z.string().min(1),
|
|
7
|
-
|
|
34
|
+
kind: kind.default("post"),
|
|
35
|
+
slug: slug.optional(),
|
|
8
36
|
excerpt: z.string().max(1024).optional(),
|
|
9
37
|
tags: z.array(z.string().max(64)).max(50).optional(),
|
|
38
|
+
categories: z.array(term).max(50).optional(),
|
|
10
39
|
cover_image_url: httpUrl.optional(),
|
|
40
|
+
cover_image_alt: z.string().max(1024).optional(),
|
|
11
41
|
canonical_url: httpUrl.optional(),
|
|
12
|
-
|
|
42
|
+
seo: z
|
|
43
|
+
.object({
|
|
44
|
+
title: z.string().min(1).max(512).optional(),
|
|
45
|
+
description: z.string().min(1).max(1024).optional(),
|
|
46
|
+
image_url: httpUrl.optional(),
|
|
47
|
+
noindex: z.boolean().optional(),
|
|
48
|
+
og_title: z.string().min(1).max(512).optional(),
|
|
49
|
+
og_description: z.string().min(1).max(1024).optional(),
|
|
50
|
+
json_ld: jsonLd.optional(),
|
|
51
|
+
})
|
|
52
|
+
.strict()
|
|
53
|
+
.optional(),
|
|
54
|
+
author: author.optional(),
|
|
13
55
|
status: z.enum(["draft", "published"]).default("draft"),
|
|
14
|
-
published_at:
|
|
15
|
-
})
|
|
56
|
+
published_at: publishedAt.optional(),
|
|
57
|
+
})
|
|
58
|
+
.strict();
|
|
59
|
+
export const PatchSchema = z
|
|
60
|
+
.object({
|
|
61
|
+
title: z.string().min(1).max(512),
|
|
62
|
+
kind,
|
|
63
|
+
markdown: z.string().min(1),
|
|
64
|
+
slug,
|
|
65
|
+
excerpt: z.string().max(1024).nullable(),
|
|
66
|
+
tags: z.array(z.string().max(64)).max(50).nullable(),
|
|
67
|
+
categories: z.array(term).max(50).nullable(),
|
|
68
|
+
cover_image_url: httpUrl.nullable(),
|
|
69
|
+
cover_image_alt: z.string().max(1024).nullable(),
|
|
70
|
+
canonical_url: httpUrl.nullable(),
|
|
71
|
+
seo: z
|
|
72
|
+
.object({
|
|
73
|
+
title: z.string().min(1).max(512),
|
|
74
|
+
description: z.string().min(1).max(1024),
|
|
75
|
+
image_url: httpUrl.nullable(),
|
|
76
|
+
noindex: z.boolean(),
|
|
77
|
+
og_title: z.string().min(1).max(512),
|
|
78
|
+
og_description: z.string().min(1).max(1024),
|
|
79
|
+
json_ld: jsonLd.nullable(),
|
|
80
|
+
})
|
|
81
|
+
.partial()
|
|
82
|
+
.strict()
|
|
83
|
+
.nullable(),
|
|
84
|
+
author: author.nullable(),
|
|
85
|
+
status: z.enum(["draft", "published"]),
|
|
86
|
+
published_at: publishedAt.nullable(),
|
|
87
|
+
})
|
|
88
|
+
.partial()
|
|
89
|
+
.strict()
|
|
90
|
+
.refine((o) => Object.keys(o).length > 0, { message: "at least one field is required" });
|
|
91
|
+
export const MediaUrlInput = z
|
|
92
|
+
.object({ url: httpUrl, alt: z.string().max(1024).optional() })
|
|
93
|
+
.strict();
|
|
94
|
+
export const MediaPatchSchema = z
|
|
95
|
+
.object({ alt: z.string().max(1024).nullable(), title: z.string().max(512).nullable() })
|
|
96
|
+
.partial()
|
|
97
|
+
.strict()
|
|
98
|
+
.refine((o) => Object.keys(o).length > 0, { message: "at least one field is required" });
|
package/dist/seo.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { SeoMetadata, SeoOverrides, StoredContent } from "./store.js";
|
|
2
|
+
/** SEO Profile 1: the overrides applied over the derived defaults. */
|
|
3
|
+
export declare function effectiveSeo(e: Pick<StoredContent, "title" | "excerpt" | "cover_image_url" | "seo">): SeoMetadata;
|
|
4
|
+
declare const KEYS: readonly ["title", "description", "image_url", "noindex", "og_title", "og_description", "json_ld"];
|
|
5
|
+
/** Overrides as sent: only the keys present, or null when nothing is overridden. */
|
|
6
|
+
export declare function cleanOverrides(seo: SeoOverrides | null | undefined): SeoOverrides | null;
|
|
7
|
+
/** PATCH semantics for `seo`: null clears; an object merges per key (a null drops that key). */
|
|
8
|
+
export declare function mergeOverrides(current: SeoOverrides | null, patch: Partial<Record<(typeof KEYS)[number], unknown>> | null): SeoOverrides | null;
|
|
9
|
+
export {};
|
package/dist/seo.js
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/** SEO Profile 1: the overrides applied over the derived defaults. */
|
|
2
|
+
export function effectiveSeo(e) {
|
|
3
|
+
const image = e.seo?.image_url ?? e.cover_image_url;
|
|
4
|
+
const title = e.seo?.title ?? e.title;
|
|
5
|
+
const description = e.seo?.description ?? (e.excerpt || e.title);
|
|
6
|
+
return {
|
|
7
|
+
title,
|
|
8
|
+
description,
|
|
9
|
+
...(image ? { image_url: image } : {}),
|
|
10
|
+
noindex: e.seo?.noindex ?? false,
|
|
11
|
+
og_title: e.seo?.og_title ?? title,
|
|
12
|
+
og_description: e.seo?.og_description ?? description,
|
|
13
|
+
...(e.seo?.json_ld !== undefined ? { json_ld: e.seo.json_ld } : {}),
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
const KEYS = ["title", "description", "image_url", "noindex", "og_title", "og_description", "json_ld"];
|
|
17
|
+
/** Overrides as sent: only the keys present, or null when nothing is overridden. */
|
|
18
|
+
export function cleanOverrides(seo) {
|
|
19
|
+
if (!seo)
|
|
20
|
+
return null;
|
|
21
|
+
const out = {};
|
|
22
|
+
for (const k of KEYS)
|
|
23
|
+
if (seo[k] !== undefined && seo[k] !== null)
|
|
24
|
+
out[k] = seo[k];
|
|
25
|
+
return Object.keys(out).length ? out : null;
|
|
26
|
+
}
|
|
27
|
+
/** PATCH semantics for `seo`: null clears; an object merges per key (a null drops that key). */
|
|
28
|
+
export function mergeOverrides(current, patch) {
|
|
29
|
+
if (patch === null)
|
|
30
|
+
return null;
|
|
31
|
+
const merged = { ...(current ?? {}) };
|
|
32
|
+
for (const k of KEYS) {
|
|
33
|
+
if (patch[k] === null)
|
|
34
|
+
delete merged[k];
|
|
35
|
+
else if (patch[k] !== undefined)
|
|
36
|
+
merged[k] = patch[k];
|
|
37
|
+
}
|
|
38
|
+
return cleanOverrides(merged);
|
|
39
|
+
}
|
package/dist/store.d.ts
CHANGED
|
@@ -1,47 +1,117 @@
|
|
|
1
|
-
export
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
export type { UpsertInput, PatchInput } from "./schema.js";
|
|
2
|
+
/** Effective SEO values (SEO Profile 1): the overrides applied over the derived defaults. */
|
|
3
|
+
export interface SeoMetadata {
|
|
4
|
+
title: string;
|
|
5
|
+
description: string;
|
|
6
|
+
image_url?: string;
|
|
7
|
+
noindex: boolean;
|
|
8
|
+
og_title: string;
|
|
9
|
+
og_description: string;
|
|
10
|
+
json_ld?: string;
|
|
11
|
+
}
|
|
12
|
+
/** What the caller overrode. Only keys the caller sent are present. */
|
|
13
|
+
export interface SeoOverrides {
|
|
14
|
+
title?: string;
|
|
15
|
+
description?: string;
|
|
16
|
+
image_url?: string;
|
|
17
|
+
noindex?: boolean;
|
|
18
|
+
og_title?: string;
|
|
19
|
+
og_description?: string;
|
|
20
|
+
json_ld?: string;
|
|
6
21
|
}
|
|
7
|
-
|
|
8
|
-
|
|
22
|
+
/** An entry as a store holds it. `url` and `etag` are finalized by the store. */
|
|
23
|
+
export interface StoredContent {
|
|
24
|
+
id: string;
|
|
25
|
+
/** The scope the entry belongs to (`ApiKey.scope`). */
|
|
26
|
+
key: string;
|
|
27
|
+
external_id: string | null;
|
|
28
|
+
kind: string;
|
|
9
29
|
title: string;
|
|
10
|
-
html: string;
|
|
11
|
-
markdown: string;
|
|
12
30
|
slug: string;
|
|
31
|
+
markdown: string;
|
|
32
|
+
html: string;
|
|
13
33
|
excerpt?: string;
|
|
14
34
|
tags?: string[];
|
|
35
|
+
categories?: string[];
|
|
15
36
|
cover_image_url?: string;
|
|
37
|
+
cover_image_alt?: string;
|
|
16
38
|
canonical_url?: string;
|
|
39
|
+
seo: SeoOverrides | null;
|
|
17
40
|
author?: {
|
|
18
41
|
name?: string;
|
|
19
42
|
email?: string;
|
|
20
43
|
};
|
|
21
44
|
status: "draft" | "published";
|
|
22
45
|
published_at: string;
|
|
46
|
+
updated_at: string;
|
|
47
|
+
version: number;
|
|
48
|
+
etag: string;
|
|
49
|
+
/** Public address, finalized by the store. */
|
|
50
|
+
url: string;
|
|
51
|
+
}
|
|
52
|
+
/** What the handlers give `save`. `id` is absent on create; present (the old id) when updating, even if kind/slug moved it. */
|
|
53
|
+
export type SaveEntry = Omit<StoredContent, "id" | "url" | "etag"> & {
|
|
54
|
+
id?: string;
|
|
55
|
+
};
|
|
56
|
+
export interface ListFilter {
|
|
57
|
+
status?: "draft" | "published";
|
|
58
|
+
kind?: string;
|
|
59
|
+
tag?: string;
|
|
60
|
+
category?: string;
|
|
61
|
+
/** Case-insensitive match over title, excerpt and markdown. */
|
|
62
|
+
search?: string;
|
|
63
|
+
external_id?: string;
|
|
64
|
+
slug?: string;
|
|
65
|
+
limit: number;
|
|
66
|
+
cursor?: string;
|
|
67
|
+
}
|
|
68
|
+
export interface ListResult {
|
|
69
|
+
items: StoredContent[];
|
|
70
|
+
next_cursor: string | null;
|
|
71
|
+
}
|
|
72
|
+
export interface StoredMedia {
|
|
73
|
+
id: string;
|
|
74
|
+
url: string;
|
|
75
|
+
alt?: string;
|
|
76
|
+
title?: string;
|
|
77
|
+
/** One of image/jpeg, png, gif, webp, avif. */
|
|
78
|
+
mime_type: string;
|
|
79
|
+
created_at: string;
|
|
80
|
+
}
|
|
81
|
+
export interface MediaListFilter {
|
|
82
|
+
/** Case-insensitive match over alt, title and filename. */
|
|
83
|
+
search?: string;
|
|
84
|
+
limit: number;
|
|
85
|
+
cursor?: string;
|
|
86
|
+
}
|
|
87
|
+
export interface MediaListResult {
|
|
88
|
+
items: StoredMedia[];
|
|
89
|
+
next_cursor: string | null;
|
|
90
|
+
}
|
|
91
|
+
export interface MediaInput {
|
|
92
|
+
bytes: Buffer;
|
|
93
|
+
/** One of image/jpeg, png, gif, webp, avif, already sniffed by the core. */
|
|
94
|
+
contentType: string;
|
|
95
|
+
filename: string;
|
|
96
|
+
alt?: string;
|
|
23
97
|
}
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
url: string;
|
|
44
|
-
slug: string;
|
|
45
|
-
created: boolean;
|
|
46
|
-
}>;
|
|
98
|
+
/**
|
|
99
|
+
* The whole storage contract: four methods (plus optional media methods), every one scoped by `key` (the `ApiKey.scope`). Slug
|
|
100
|
+
* conflicts and external_id lookups go through `list` with exact filters, so implement those
|
|
101
|
+
* efficiently. `saveMedia` is optional: a store without it makes the receiver omit the `media`
|
|
102
|
+
* feature.
|
|
103
|
+
*/
|
|
104
|
+
export interface ContentStore {
|
|
105
|
+
get(key: string, id: string): Promise<StoredContent | null>;
|
|
106
|
+
list(key: string, filter: ListFilter): Promise<ListResult>;
|
|
107
|
+
save(key: string, entry: SaveEntry): Promise<StoredContent>;
|
|
108
|
+
remove(key: string, id: string): Promise<boolean>;
|
|
109
|
+
saveMedia?(key: string, media: MediaInput): Promise<StoredMedia>;
|
|
110
|
+
/** Newest first by `created_at`, ties by `id`; `recencyKey` and `pageOf` (list.ts) do the paging. A store without it omits `media_list`. */
|
|
111
|
+
listMedia?(key: string, filter: MediaListFilter): Promise<MediaListResult>;
|
|
112
|
+
/** `null` clears. Returns null for an unknown id. A store without it omits `media_update`. */
|
|
113
|
+
updateMedia?(key: string, id: string, patch: {
|
|
114
|
+
alt?: string | null;
|
|
115
|
+
title?: string | null;
|
|
116
|
+
}): Promise<StoredMedia | null>;
|
|
47
117
|
}
|
package/dist/store.js
CHANGED
|
@@ -1,18 +1 @@
|
|
|
1
|
-
export
|
|
2
|
-
byExt = new Map();
|
|
3
|
-
bySlug = new Map();
|
|
4
|
-
seq = 0;
|
|
5
|
-
k(key, id) { return `${key}::${id}`; }
|
|
6
|
-
async findByExternalId(key, externalId) { return this.byExt.get(this.k(key, externalId)) ?? null; }
|
|
7
|
-
async findBySlug(key, slug) { return this.bySlug.get(this.k(key, slug)) ?? null; }
|
|
8
|
-
async upsert(key, post) {
|
|
9
|
-
const existing = this.byExt.get(this.k(key, post.external_id));
|
|
10
|
-
const id = existing?.id ?? String(++this.seq);
|
|
11
|
-
const slug = post.slug;
|
|
12
|
-
const url = `https://demo.local/blog/${slug}`;
|
|
13
|
-
const rec = { id, slug, url, external_id: post.external_id };
|
|
14
|
-
this.byExt.set(this.k(key, post.external_id), rec);
|
|
15
|
-
this.bySlug.set(this.k(key, slug), rec);
|
|
16
|
-
return { id, url, slug, created: !existing };
|
|
17
|
-
}
|
|
18
|
-
}
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { ContentStore, ListFilter, ListResult, MediaInput, MediaListFilter, MediaListResult, SaveEntry, StoredContent, StoredMedia } from "../store.js";
|
|
2
|
+
export interface FileStoreOptions {
|
|
3
|
+
/** The content directory: `<root>/<kind>/<slug>.md`. */
|
|
4
|
+
root: string;
|
|
5
|
+
/** Public base of `<root>/media`, no trailing slash. Media url = `${mediaUrlBase}/<filename>`. */
|
|
6
|
+
mediaUrlBase: string;
|
|
7
|
+
/** Public address of an entry. Default: the origin of `mediaUrlBase` + `/<kind>/<slug>`. */
|
|
8
|
+
urlFor?: (e: {
|
|
9
|
+
kind: string;
|
|
10
|
+
slug: string;
|
|
11
|
+
}) => string;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Entries as markdown files with YAML frontmatter, so a repo of existing `.md` files is readable
|
|
15
|
+
* on day one (missing frontmatter defaults: title from the first `# ` heading, external_id null,
|
|
16
|
+
* status published, kind from the folder, dates from the file). One FileStore is one site: the
|
|
17
|
+
* `key` argument is stamped on what it returns, not used to partition directories. Files whose
|
|
18
|
+
* name is not a slug (`^[a-z0-9-]+$`) or whose frontmatter is not valid YAML are not addressable
|
|
19
|
+
* and stay hidden rather than guessed at.
|
|
20
|
+
*/
|
|
21
|
+
export declare class FileStore implements ContentStore {
|
|
22
|
+
private root;
|
|
23
|
+
private mediaBase;
|
|
24
|
+
private urlFor;
|
|
25
|
+
private cache;
|
|
26
|
+
constructor(opts: FileStoreOptions);
|
|
27
|
+
private fileFor;
|
|
28
|
+
private read;
|
|
29
|
+
get(key: string, id: string): Promise<{
|
|
30
|
+
key: string;
|
|
31
|
+
html: string;
|
|
32
|
+
title: string;
|
|
33
|
+
status: "draft" | "published";
|
|
34
|
+
external_id: string | null;
|
|
35
|
+
markdown: string;
|
|
36
|
+
kind: string;
|
|
37
|
+
slug: string;
|
|
38
|
+
excerpt?: string | undefined;
|
|
39
|
+
tags?: string[] | undefined;
|
|
40
|
+
categories?: string[] | undefined;
|
|
41
|
+
cover_image_url?: string | undefined;
|
|
42
|
+
cover_image_alt?: string | undefined;
|
|
43
|
+
canonical_url?: string | undefined;
|
|
44
|
+
seo: import("../store.js").SeoOverrides | null;
|
|
45
|
+
author?: {
|
|
46
|
+
name?: string;
|
|
47
|
+
email?: string;
|
|
48
|
+
} | undefined;
|
|
49
|
+
published_at: string;
|
|
50
|
+
url: string;
|
|
51
|
+
id: string;
|
|
52
|
+
etag: string;
|
|
53
|
+
updated_at: string;
|
|
54
|
+
version: number;
|
|
55
|
+
} | null>;
|
|
56
|
+
list(key: string, filter: ListFilter): Promise<ListResult>;
|
|
57
|
+
save(key: string, entry: SaveEntry): Promise<StoredContent>;
|
|
58
|
+
remove(_key: string, id: string): Promise<boolean>;
|
|
59
|
+
private writeAtomic;
|
|
60
|
+
saveMedia(_key: string, m: MediaInput): Promise<StoredMedia>;
|
|
61
|
+
private readMedia;
|
|
62
|
+
listMedia(_key: string, filter: MediaListFilter): Promise<MediaListResult>;
|
|
63
|
+
updateMedia(_key: string, id: string, patch: {
|
|
64
|
+
alt?: string | null;
|
|
65
|
+
title?: string | null;
|
|
66
|
+
}): Promise<StoredMedia | null>;
|
|
67
|
+
}
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
import { createHash, randomBytes } from "node:crypto";
|
|
2
|
+
import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { InkwireError } from "../errors.js";
|
|
5
|
+
import { KIND_RE, RESERVED_KINDS, SLUG_FILE_RE, idFor, parseEntryFile, parseId, serializeEntry, updateEntryFile } from "../files.js";
|
|
6
|
+
import { matches, pageMedia, pageOf, recencyKey } from "../list.js";
|
|
7
|
+
import { MEDIA_FILE_RE, MEDIA_ID_RE, META_SUFFIX, parseMeta, patchMeta, serializeMeta, toMedia } from "../media-meta.js";
|
|
8
|
+
/**
|
|
9
|
+
* Entries as markdown files with YAML frontmatter, so a repo of existing `.md` files is readable
|
|
10
|
+
* on day one (missing frontmatter defaults: title from the first `# ` heading, external_id null,
|
|
11
|
+
* status published, kind from the folder, dates from the file). One FileStore is one site: the
|
|
12
|
+
* `key` argument is stamped on what it returns, not used to partition directories. Files whose
|
|
13
|
+
* name is not a slug (`^[a-z0-9-]+$`) or whose frontmatter is not valid YAML are not addressable
|
|
14
|
+
* and stay hidden rather than guessed at.
|
|
15
|
+
*/
|
|
16
|
+
export class FileStore {
|
|
17
|
+
root;
|
|
18
|
+
mediaBase;
|
|
19
|
+
urlFor;
|
|
20
|
+
cache = new Map();
|
|
21
|
+
constructor(opts) {
|
|
22
|
+
this.root = path.resolve(opts.root);
|
|
23
|
+
this.mediaBase = opts.mediaUrlBase.replace(/\/+$/, "");
|
|
24
|
+
this.urlFor =
|
|
25
|
+
opts.urlFor ??
|
|
26
|
+
((e) => {
|
|
27
|
+
let origin = this.mediaBase;
|
|
28
|
+
try {
|
|
29
|
+
origin = new URL(this.mediaBase).origin;
|
|
30
|
+
}
|
|
31
|
+
catch { }
|
|
32
|
+
return `${origin}/${e.kind}/${e.slug}`;
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
fileFor(kind, slug) {
|
|
36
|
+
if (!KIND_RE.test(kind) || RESERVED_KINDS.has(kind)) {
|
|
37
|
+
throw new InkwireError("invalid_payload", `kind "${kind}" cannot be stored as a folder`);
|
|
38
|
+
}
|
|
39
|
+
if (!SLUG_FILE_RE.test(slug))
|
|
40
|
+
throw new InkwireError("invalid_payload", `slug "${slug}" is not a valid filename`);
|
|
41
|
+
const full = path.join(this.root, kind, `${slug}.md`);
|
|
42
|
+
if (path.relative(this.root, full).startsWith(".."))
|
|
43
|
+
throw new InkwireError("invalid_payload", "path escapes the content directory");
|
|
44
|
+
return full;
|
|
45
|
+
}
|
|
46
|
+
async read(kind, slug) {
|
|
47
|
+
const file = this.fileFor(kind, slug);
|
|
48
|
+
let st;
|
|
49
|
+
try {
|
|
50
|
+
st = await stat(file);
|
|
51
|
+
}
|
|
52
|
+
catch (e) {
|
|
53
|
+
if (e.code === "ENOENT" || e.code === "ENOTDIR")
|
|
54
|
+
return null;
|
|
55
|
+
throw e;
|
|
56
|
+
}
|
|
57
|
+
if (!st.isFile())
|
|
58
|
+
return null;
|
|
59
|
+
const sig = `${st.mtimeMs}:${st.size}`;
|
|
60
|
+
const hit = this.cache.get(file);
|
|
61
|
+
if (hit?.sig === sig)
|
|
62
|
+
return hit.entry;
|
|
63
|
+
const raw = await readFile(file, "utf8");
|
|
64
|
+
const draft = parseEntryFile(raw, { kind, slug, mtimeIso: st.mtime.toISOString() });
|
|
65
|
+
const entry = draft
|
|
66
|
+
? {
|
|
67
|
+
...draft,
|
|
68
|
+
id: idFor(kind, slug),
|
|
69
|
+
url: this.urlFor({ kind, slug }),
|
|
70
|
+
etag: `${st.mtimeMs.toString(36)}-${st.size.toString(36)}-${createHash("sha1").update(raw).digest("hex").slice(0, 10)}`,
|
|
71
|
+
}
|
|
72
|
+
: null;
|
|
73
|
+
this.cache.set(file, { sig, entry });
|
|
74
|
+
return entry;
|
|
75
|
+
}
|
|
76
|
+
async get(key, id) {
|
|
77
|
+
const p = parseId(id);
|
|
78
|
+
if (!p)
|
|
79
|
+
return null;
|
|
80
|
+
const e = await this.read(p.kind, p.slug);
|
|
81
|
+
return e ? { ...e, key } : null;
|
|
82
|
+
}
|
|
83
|
+
async list(key, filter) {
|
|
84
|
+
let kinds;
|
|
85
|
+
if (filter.kind) {
|
|
86
|
+
kinds = KIND_RE.test(filter.kind) && !RESERVED_KINDS.has(filter.kind) ? [filter.kind] : [];
|
|
87
|
+
}
|
|
88
|
+
else {
|
|
89
|
+
const dirs = await readdir(this.root, { withFileTypes: true }).catch(() => []);
|
|
90
|
+
kinds = dirs.filter((d) => d.isDirectory() && KIND_RE.test(d.name) && !RESERVED_KINDS.has(d.name)).map((d) => d.name);
|
|
91
|
+
}
|
|
92
|
+
const found = [];
|
|
93
|
+
for (const kind of kinds) {
|
|
94
|
+
let slugs;
|
|
95
|
+
if (filter.slug) {
|
|
96
|
+
slugs = SLUG_FILE_RE.test(filter.slug) ? [filter.slug] : [];
|
|
97
|
+
}
|
|
98
|
+
else {
|
|
99
|
+
const files = await readdir(path.join(this.root, kind)).catch(() => []);
|
|
100
|
+
slugs = files.filter((f) => f.endsWith(".md") && SLUG_FILE_RE.test(f.slice(0, -3))).map((f) => f.slice(0, -3));
|
|
101
|
+
}
|
|
102
|
+
for (const slug of slugs) {
|
|
103
|
+
const e = await this.read(kind, slug);
|
|
104
|
+
if (e) {
|
|
105
|
+
const withKey = { ...e, key };
|
|
106
|
+
if (matches(withKey, filter))
|
|
107
|
+
found.push(withKey);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
found.sort((a, b) => (recencyKey(a) < recencyKey(b) ? -1 : 1));
|
|
112
|
+
return pageOf(found, recencyKey, filter.limit, filter.cursor);
|
|
113
|
+
}
|
|
114
|
+
async save(key, entry) {
|
|
115
|
+
const file = this.fileFor(entry.kind, entry.slug);
|
|
116
|
+
const newId = idFor(entry.kind, entry.slug);
|
|
117
|
+
// Never overwrite a file that is not this entry (including one whose frontmatter we cannot read).
|
|
118
|
+
if (entry.id !== newId) {
|
|
119
|
+
const taken = await stat(file).then(() => true, () => false);
|
|
120
|
+
if (taken)
|
|
121
|
+
throw new InkwireError("conflict", `${entry.kind}/${entry.slug}.md already exists`);
|
|
122
|
+
}
|
|
123
|
+
await mkdir(path.dirname(file), { recursive: true });
|
|
124
|
+
// An edit of an existing file changes only what changed in it (its own frontmatter keys survive).
|
|
125
|
+
const old = entry.id ? parseId(entry.id) : null;
|
|
126
|
+
let text = null;
|
|
127
|
+
if (old) {
|
|
128
|
+
const before = await this.read(old.kind, old.slug).catch(() => null);
|
|
129
|
+
const raw = before ? await readFile(this.fileFor(old.kind, old.slug), "utf8").catch(() => null) : null;
|
|
130
|
+
if (before && raw !== null)
|
|
131
|
+
text = updateEntryFile(raw, before, entry);
|
|
132
|
+
}
|
|
133
|
+
const tmp = path.join(path.dirname(file), `.${entry.slug}.${randomBytes(6).toString("hex")}.tmp`);
|
|
134
|
+
try {
|
|
135
|
+
await writeFile(tmp, text ?? serializeEntry(entry), { encoding: "utf8", mode: 0o644 });
|
|
136
|
+
await rename(tmp, file);
|
|
137
|
+
}
|
|
138
|
+
catch (e) {
|
|
139
|
+
await unlink(tmp).catch(() => { });
|
|
140
|
+
throw e;
|
|
141
|
+
}
|
|
142
|
+
if (entry.id && entry.id !== newId) {
|
|
143
|
+
const old = parseId(entry.id);
|
|
144
|
+
if (old)
|
|
145
|
+
await unlink(this.fileFor(old.kind, old.slug)).catch(() => { });
|
|
146
|
+
}
|
|
147
|
+
this.cache.delete(file);
|
|
148
|
+
const saved = await this.read(entry.kind, entry.slug);
|
|
149
|
+
if (!saved)
|
|
150
|
+
throw new InkwireError("internal", "the entry was written but could not be read back");
|
|
151
|
+
return { ...saved, key };
|
|
152
|
+
}
|
|
153
|
+
async remove(_key, id) {
|
|
154
|
+
const p = parseId(id);
|
|
155
|
+
if (!p)
|
|
156
|
+
return false;
|
|
157
|
+
const file = this.fileFor(p.kind, p.slug);
|
|
158
|
+
try {
|
|
159
|
+
await unlink(file);
|
|
160
|
+
}
|
|
161
|
+
catch (e) {
|
|
162
|
+
if (e.code === "ENOENT")
|
|
163
|
+
return false;
|
|
164
|
+
throw e;
|
|
165
|
+
}
|
|
166
|
+
this.cache.delete(file);
|
|
167
|
+
return true;
|
|
168
|
+
}
|
|
169
|
+
async writeAtomic(file, data) {
|
|
170
|
+
const tmp = path.join(path.dirname(file), `.${randomBytes(6).toString("hex")}.tmp`);
|
|
171
|
+
try {
|
|
172
|
+
await writeFile(tmp, data);
|
|
173
|
+
await rename(tmp, file);
|
|
174
|
+
}
|
|
175
|
+
catch (e) {
|
|
176
|
+
await unlink(tmp).catch(() => { });
|
|
177
|
+
throw e;
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
async saveMedia(_key, m) {
|
|
181
|
+
const dir = path.join(this.root, "media");
|
|
182
|
+
await mkdir(dir, { recursive: true });
|
|
183
|
+
const hex = randomBytes(8).toString("hex");
|
|
184
|
+
const name = `${hex}-${m.filename}`;
|
|
185
|
+
const file = path.join(dir, name);
|
|
186
|
+
const meta = { ...(m.alt !== undefined ? { alt: m.alt } : {}), content_type: m.contentType, created_at: new Date().toISOString() };
|
|
187
|
+
await this.writeAtomic(file, m.bytes);
|
|
188
|
+
await this.writeAtomic(`${file}${META_SUFFIX}`, serializeMeta(meta));
|
|
189
|
+
return toMedia(hex, `${this.mediaBase}/${name}`, meta);
|
|
190
|
+
}
|
|
191
|
+
async readMedia(dir, name) {
|
|
192
|
+
const m = MEDIA_FILE_RE.exec(name);
|
|
193
|
+
if (!m || name.endsWith(META_SUFFIX))
|
|
194
|
+
return null;
|
|
195
|
+
const file = path.join(dir, name);
|
|
196
|
+
const st = await stat(file).catch(() => null);
|
|
197
|
+
if (!st?.isFile())
|
|
198
|
+
return null;
|
|
199
|
+
const raw = await readFile(`${file}${META_SUFFIX}`, "utf8").catch(() => null);
|
|
200
|
+
return toMedia(m[1], `${this.mediaBase}/${name}`, parseMeta(raw, name, st.mtime.toISOString()));
|
|
201
|
+
}
|
|
202
|
+
async listMedia(_key, filter) {
|
|
203
|
+
const dir = path.join(this.root, "media");
|
|
204
|
+
const names = await readdir(dir).catch(() => []);
|
|
205
|
+
const all = [];
|
|
206
|
+
for (const name of names) {
|
|
207
|
+
const item = await this.readMedia(dir, name);
|
|
208
|
+
if (item)
|
|
209
|
+
all.push(item);
|
|
210
|
+
}
|
|
211
|
+
return pageMedia(all, filter);
|
|
212
|
+
}
|
|
213
|
+
async updateMedia(_key, id, patch) {
|
|
214
|
+
if (!MEDIA_ID_RE.test(id))
|
|
215
|
+
return null;
|
|
216
|
+
const dir = path.join(this.root, "media");
|
|
217
|
+
const name = (await readdir(dir).catch(() => [])).find((n) => n.startsWith(`${id}-`) && !n.endsWith(META_SUFFIX));
|
|
218
|
+
if (!name)
|
|
219
|
+
return null;
|
|
220
|
+
const cur = await this.readMedia(dir, name);
|
|
221
|
+
if (!cur)
|
|
222
|
+
return null;
|
|
223
|
+
const meta = patchMeta({ ...(cur.alt !== undefined ? { alt: cur.alt } : {}), ...(cur.title !== undefined ? { title: cur.title } : {}), content_type: cur.mime_type, created_at: cur.created_at }, patch);
|
|
224
|
+
await this.writeAtomic(path.join(dir, `${name}${META_SUFFIX}`), serializeMeta(meta));
|
|
225
|
+
return toMedia(id, cur.url, meta);
|
|
226
|
+
}
|
|
227
|
+
}
|