# HG changeset patch
# User Kim Alvefur <zash@zash.se>
# Date 1480187440 -3600
# Node ID 4d9186d990a5f5fe29a07cb7999fd723323645b5
# Parent  d018ffc9238cbb80fb7eb8901cc40522c096f341
doc: Add a description of the Storage API in TypedLua format

diff -r d018ffc9238c -r 4d9186d990a5 doc/storage.tld
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/storage.tld	Sat Nov 26 20:10:40 2016 +0100
@@ -0,0 +1,61 @@
+-- Storage Interface API Description
+--
+-- This is written as a TypedLua description
+
+-- Key-Value stores (the default)
+
+interface keyval_store
+	get : ( self, string? ) -> (any) | (nil, string)
+	set : ( self, string?, any ) -> (boolean) | (nil, string)
+end
+
+-- Map stores (key-key-value stores)
+
+interface map_store
+	get : ( self, string?, any ) -> (any) | (nil, string)
+	set : ( self, string?, any, any ) -> (boolean) | (nil, string)
+	set_keys : ( self, string?, { any : any }) -> (boolean) | (nil, string)
+	remove : {}
+end
+
+-- Archive stores
+
+typealias archive_query = {
+	"start"  : number?, -- timestamp
+	"end"    : number?, -- timestamp
+	"with"   : string?,
+	"after"  : string?, -- archive id
+	"before" : string?, -- archive id
+	"total"  : boolean?,
+}
+
+interface archive_store
+	-- Optional set of capabilities
+	caps   : {
+		-- Optional total count of matching items returned as second return value from :find()
+		"total" : boolean?,
+	}?
+
+	-- Add to the archive
+	append : ( self, string?, string?, any, number?, string? ) -> (string) | (nil, string)
+
+	-- Iterate over archive
+	find   : ( self, string?, archive_query? ) -> ( () -> ( string, any, number?, string? ), integer? )
+
+	-- Removal of items. API like find. Optional?
+	delete : ( self, string?, archive_query? ) -> (boolean) | (number) | (nil, string)
+
+	-- Array of dates which do have messages (Optional?)
+	dates  : ( self, string? ) -> ({ string }) | (nil, string)
+end
+
+-- This represents moduleapi
+interface module
+	-- If the first string is omitted then the name of the module is used
+	-- The second string is one of "keyval" (default), "map" or "archive"
+	open_store : (self, string?, string?) -> (keyval_store) | (map_store) | (archive_store) | (nil, string)
+
+	-- Other module methods omitted
+end
+
+module : module