From 6a0dc89c459b8f095bcff4d4bacfb6e6b835370f Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Thu, 1 Sep 2022 11:12:13 +0300
Subject: [PATCH] notes and API docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 pwiki/store/base.js | 47 +++++++++++++++++++++++++++++++++++++++++++++
 pwiki2.js           |  9 +++++++++
 2 files changed, 56 insertions(+)

diff --git a/pwiki/store/base.js b/pwiki/store/base.js
index bd0d13e..5bec6da 100755
--- a/pwiki/store/base.js
+++ b/pwiki/store/base.js
@@ -54,6 +54,53 @@ function(name, get, update, ...args){
 //---------------------------------------------------------------------
 // Store...
 
+//
+// API levels:
+// 	Level 1 -- implementation API
+// 		This level is the base API, this is used by all other Levels.
+// 		This is the only level that needs to be fully overloaded by store 
+// 		implementations (no super calls necessary).
+// 		The base methods that need to be overloaded for the store to work:
+// 			.__paths__()
+// 				-> <keys>
+// 			.__exists__(path, ..)
+// 				-> <path>
+// 				-> false
+// 			.__get__(path, ..)
+// 				-> <data>
+// 		Optional for r/w stores:
+// 			.__update__(path, ..)
+// 			.__delete__(path, ..)
+// 	Level 2 -- feature API
+// 		This can use Level 1 and Level 2 internally.
+// 		When overloading it is needed to to call the super method to 
+// 		retain base functionality.
+// 		All overloading here is optional.
+// 			.paths()
+// 				-> <path-list>
+// 			.names()
+// 				-> <name-index>
+// 			.exists(<path>)
+// 				-> <real-path>
+// 				-> false
+// 			.get(<path>)
+// 				-> <data>
+// 				-> undefined
+// 			.metadata(<path>[, <data>])
+// 				-> <store> -- on write
+// 				-> <data>
+// 				-> undefined
+// 			.update(<path>, <data>)
+// 				-> <store>
+// 			.delete(<path>)
+// 				-> <store>
+// 			.load(..)
+// 				-> <store>
+// 			.json(..)
+// 				-> <json>
+// 	Level 3
+// 		...
+//
 //
 // To create a store adapter:
 // 		- inherit from BaseStore
diff --git a/pwiki2.js b/pwiki2.js
index d35e7cc..60263b6 100755
--- a/pwiki2.js
+++ b/pwiki2.js
@@ -1,6 +1,9 @@
 /**********************************************************************
 * 
 *
+* XXX might be a good idea to make some methods that only access the 
+* 		index sync -- this will make the store unusable while indexing 
+* 		though...
 * XXX ASAP prevent paths from using reserved chars like: ":", "#", ...
 * XXX FEATURE list macro paging...
 * 		...should this be macro level or handled in .each()
@@ -34,6 +37,12 @@
 * 			/some/path/!action
 * 			..."!" is removed before the <store>.__<name>__(..) calls...
 * XXX ENERGETIC revise naming...
+* XXX OPTIMIZE might be a good idea to move stuff down the stack to Store:
+* 			.each()	-> .store.each(<path>)
+* 		...this will enable ups to optimize page loading on a store 
+* 		level...
+* 		...another approach would be to make .get(..) accept a list of 
+* 		paths and return an iterator...
 * XXX OPTIMIZE page search: make things invariant via .names
 * 			- if a page is in a system path and there are no alternatives 
 * 				just return it and do not search.