@sphido/core 1.0.11 → 2.0.1

package/LICENSE.md

@@ -1,7 +1,7 @@
 MIT License
 -----------
 
-Copyright (c) 2021 Roman Ožana (https://ozana.cz/)
+Copyright (c) 2022 Roman Ožana (https://ozana.cz/)
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation
 files (the "Software"), to deal in the Software without

package/lib/all-pages.js

@@ -0,0 +1,13 @@
+/**
+ * Page generator that flatten pages structure
+ * @param {array} pages
+ */
+export function * allPages(pages) {
+	for (const page of pages) {
+		if (page?.children) {
+			yield * allPages(page.children);
+		} else {
+			yield page;
+		}
+	}
+}

package/lib/get-pages.js

@@ -1,13 +1,33 @@
-import {getPage} from './get-page.js';
+import {join, parse} from 'node:path';
+import {readdir} from 'node:fs/promises';
+import {isPage} from './is-page.js';
 
 /**
- * Return list of pages from directory
- * @param {Array} files
- * @param {Array} extenders
- * @returns {Promise<any[]>}
+ * Retrieve an array tree of pages from path
+ * @param {string} path
+ * @param {Function} include
+ * @param extenders
+ * @returns {Promise<Awaited<unknown>[{name, path}]>}
  */
-export const getPages = async (files, ...extenders) => Promise.all(
-	files.map(
-		file => getPage(file, ...extenders),
-	),
-);
+export async function getPages({path = 'content', include = isPage} = {}, ...extenders) {
+	const dir = await readdir(path, {withFileTypes: true});
+
+	return Promise.all(
+		dir
+			.filter(dirent => include(dirent))
+			.map(async dirent => {
+				// Page
+				const page = {name: parse(dirent.name).name, path: join(path, dirent.name)};
+
+				// Read subdirectory recursively
+				if (dirent.isDirectory()) {
+					page.children = await getPages({path: page.path, isPage: include}, ...extenders);
+				}
+
+				// Calling callbacks
+				await Promise.all(extenders.filter(f => typeof f === 'function').map(f => f(page, dirent, path)));
+
+				// Assign objects with page
+				return Object.assign(page, ...extenders.filter(o => typeof o === 'object'));
+			}));
+}

package/lib/index.js

@@ -1,2 +1,4 @@
 export {getPages} from './get-pages.js';
-export {getPage} from './get-page.js';
+export {allPages} from './all-pages.js';
+export {readFile} from './read-file.js';
+export {writeFile} from './write-file.js';

package/lib/is-page.js

@@ -0,0 +1,20 @@
+/**
+ * Default page filter
+ *
+ * - skip hidden files (starts with .)
+ * - skip and directories (starts with .)
+ * - skip drafts files with underscore at the beginning
+ * - accept only *.html and *.md files
+ *
+ * @param {object} dirent
+ * @returns {boolean}
+ */
+export function isPage(dirent) {
+	// Accept only *.md, *.html files
+	if (dirent.isFile() && !dirent.name.startsWith('_') && !dirent.name.startsWith('.')) {
+		return dirent.name.endsWith('.md') || dirent.name.endsWith('.html');
+	}
+
+	// Or not hidden directory
+	return dirent.isDirectory() && !dirent.name.startsWith('.');
+}

package/lib/read-file.js

@@ -0,0 +1,10 @@
+import {readFile as readFileAsync} from 'node:fs/promises';
+
+/**
+ * Read file content as string
+ * @param {string} path
+ * @returns {Promise<*>}
+ */
+export async function readFile(path) {
+	return readFileAsync(path, 'utf8');
+}

package/lib/write-file.js

@@ -0,0 +1,18 @@
+import {mkdir, writeFile as writeFileAsync} from 'node:fs/promises';
+import {existsSync} from 'node:fs';
+import {dirname} from 'node:path';
+
+/**
+ * Write content to the file and create directory if not exists
+ *
+ * @param {string} file
+ * @param {string} content
+ * @returns {Promise<*>}
+ */
+export async function writeFile(file, content) {
+	if (!existsSync(dirname(file))) {
+		await mkdir(dirname(file), {recursive: true});
+	}
+
+	return writeFileAsync(file, content);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sphido/core",
-	"version": "1.0.11",
+	"version": "2.0.1",
 	"author": {
 		"name": "Roman Ožana",
 		"email": "roman@ozana.cz",
@@ -11,7 +11,7 @@
 	"type": "module",
 	"exports": "./lib/index.js",
 	"engines": {
-		"node": ">=12"
+		"node": ">=14"
 	},
 	"keywords": [
 		"markdown",
@@ -33,10 +33,12 @@
 		"url": "git@github.com:sphido/sphido.git"
 	},
 	"devDependencies": {
-		"ava": "^4.2.0"
+		"@sindresorhus/slugify": "^2.1.0",
+		"ava": "^4.2.0",
+		"marked": "^4.0.17"
 	},
 	"scripts": {
 		"test": "ava"
 	},
-	"gitHead": "538e6fa2ee43383c6728ceaf23e6f8fdd7f4ace4"
+	"gitHead": "75cf4126bc6027237f192873c51c0d636aacd0ab"
 }

package/readme.md

@@ -1,25 +1,117 @@
 # @sphido/core
 
-Core contains most important [`getPage()`](https://github.com/sphido/sphido/blob/main/packages/sphido-core/lib/get-page.js) 
-and [`getPages()`](https://github.com/sphido/sphido/blob/main/packages/sphido-core/lib/get-pages.js) functions.
+Sphido core package contains two most important function `getPages()` and `allPages()`.
+The `getPages()` function scans directories for all `*.md` and `*.html` files.
+Second function `allPages()` is [generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator)
+that allow to iterate over all pages.
 
-* `getPage(file, [...extenders])` - returns a `page` object generated from file.
-* `getPages(files, [...extenders])` - returns array of `page` objects from list of files. 
+```javascript
+const pages = await getPages({path: 'content'}, /* ...exteners */);
+```
 
-Basic page object looks like bellow:
+Returned structure is very simple and looks like follow:
 
 ```json
-{
-  "file":"path to the file",
-  "dir": " directory to the file",
-  "base" : "file basename without extension",
-  "content": "content of file"
+[
+	{
+		"name": "Main page",
+		"path": "content/Main page.md"
+	},
+	{
+		"name": "Directory",
+		"children": [
+			{
+				"name": "Subpage one",
+				"path": "content/Directory/Subpage one.md"
+			},
+			{
+				"name": "Subpage two",
+				"path": "content/Directory/Subpage two.md"
+			}
+		]
+	}
+]
+```
+
+Then iterate over pages like follow:
+
+```javascript
+for (const page of allPages(pages)) {
+	console.log(page);
+}
+```
+
+## Extend
+
+Every single `page` object inside structure can be modified with extender. Extenders are set as additional parameters of the `getPages()` function.
+There are two types of extenders:
+
+### *callback* extenders
+
+Callback extender is a function that is called during recursion over each page with three
+parameters passed to the function `page`, `path` and [`dirent`](https://nodejs.org/api/fs.html#class-fsdirent).
+
+```javascript
+const callbackExtender = (page, path, dirent) => {
+	// do anything with page object
+}
+
+const pages = await getPages({path: 'content'}, callbackExtender);
+```
+
+### *object* extenders
+
+This extender is just a simple JavaScript object that is combined with the `page` object using the  [Object.assign()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) function.
+
+```javascript
+const objectExtender = {
+	author: 'Roman Ožana'
 }
+
+const pages = await getPages({path: 'content'}, objectExtender);
+```
+
+There is no limit to the number of extenders, you can combine as many as you want.
+Let's have the following code:
+
+```javascript
+const extenders = [
+	// callback extender will be called during iteration
+	(page) => {
+		// add property
+		page.title = `${page.name} | my best website`;
+		// or function
+		page.getDate = () => new Date();
+	},
+
+	// object extender will be merged with page object
+	{
+		"author": "Roman Ožana",
+		"getLink": function () {
+			return this.path.replace('content', 'public');
+		}
+	}
+];
+
+const pages = getPages({path: 'content'}, ...extenders);
 ```
 
-Pages are merged inside `getPage()` function together with `extenders`. Extender can be `object` or `function`.    
+then you get this structure:
 
-## Install
+```json
+[
+	{
+		"name": "Main page",
+		"path": "content/Main page.md",
+		"title": "Main page | my best website",
+		"author": "Roman Ožana",
+		"getDate": "[Function: getDate]",
+		"getLink": "[Function: getLink]"
+	}
+]
+```
+
+## Installation
 
 ```bash
 yarn add @sphido/core
@@ -27,25 +119,36 @@ yarn add @sphido/core
 
 ## Example
 
+Following example read all `*.md` files in `content` directory and process them with [marked](https://github.com/markedjs/marked) to HTML files
+
 ```javascript
-import globby from 'globby';
-import {getPages} from '@sphido/core';
+#!/usr/bin/env node
 
-(async () => {
-  const pages = await getPages(
-    await globby('content/**/*.{md,html}')
-  );
-})();
-```
+import {dirname, relative, join} from 'node:path';
+import {getPages, allPages, readFile, writeFile} from '@sphido/core';
+import slugify from '@sindresorhus/slugify';
+import {marked} from 'marked';
 
-You can also process single page like follow:
+function getHtml({name, content, path}) {
+	return `<!DOCTYPE html>
+<html lang="cs" dir="ltr">
+<head>
+	<meta charset="UTF-8">
+	<script src="https://cdn.tailwindcss.com?plugins=typography"></script>
+	<title>${name} | Sphido Example page</title>	
+</head>
+<body class="prose mx-auto my-6">${content}</body>
+<!-- Generated with Sphido from ${path} -->
+</html>`;
+}
 
-```javascript
-import {getPage} from '@sphido/core';
+const pages = await getPages({path: 'content'});
 
-(async () => {
-  const page = await getPage('example.md');
-})();
+for (const page of allPages(pages)) {
+	page.output = join('public', relative('content', dirname(page.path)), slugify(page.name) + '.html');
+	page.content = marked(await readFile(page.path));
+	await writeFile(page.output, getHtml(page));
+}
 ```
 
 ## Source codes

package/lib/get-page.js

@@ -1,29 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import {promisify} from 'node:util';
-
-const readFile = promisify(fs.readFile);
-
-/**
- * Return {page} object
- * @param {String} file
- * @param {Object.<string, number>} extenders
- * @returns {Promise<*>}
- */
-export async function getPage(file, ...extenders) {
-	const ext = path.extname(file);
-
-	const page = {
-		file,
-		dir: path.relative('.', path.dirname(file)),
-		ext,
-		base: path.basename(file, ext),
-		content: await readFile(file, 'utf8'),
-	};
-
-	// Callbacks only
-	extenders.filter(f => typeof f === 'function').map(f => f(page));
-
-	// Assign objects
-	return Object.assign(page, ...extenders.filter(f => typeof f === 'object'));
-}