1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7
8. 8
9. 9
10. 10
11. 11
12. 12
13. 13
14. 14
15. 15
16. 16
17. 17
18. 18
19. 19
20. 20
21. 21
22. 22
23. 23
24. 24
25. 25
26. 26
27. 27
28. 28
29. 29
30. 30
31. 31
32. 32
33. 33
34. 34
35. 35
36. 36
37. 37
38. 38
39. 39
40. 40
41. 41
42. 42
43. 43
44. 44
45. 45
46. 46
47. 47
48. 48
49. 49
50. 50
51. 51
52. 52
53. 53
54. 54
55. 55
56. 56
57. 57
58. 58
59. 59
60. 60
61. 61
62. 62
63. 63
64. 64
65. 65
66. 66
67. 67
68. 68
69. 69
70. 70
71. 71
72. 72
73. 73
74. 74
75. 75
76. 76
77. 77
78. 78
79. 79
80. 80
81. 81
82. 82
83. 83
84. 84
85. 85
86. 86
87. 87
88. 88
89. 89
90. 90
91. 91
92. 92
93. 93
94. 94
95. 95
96. 96
97. 97
98. 98
99. 99
100. 100
101. 101
102. 102
103. 103
104. 104
105. 105
106. 106
107. 107
108. 108
109. 109
110. 110
111. 111
112. 112
113. 113
114. 114
115. 115
116. 116
117. 117
118. 118
119. 119
120. 120
121. 121
122. 122
123. 123
124. 124
125. 125
126. 126
127. 127
128. 128
129. 129
130. 130
131. 131
132. 132
133. 133
134. 134
135. 135
136. 136
137. 137
138. 138
139. 139
140. 140
141. 141
142. 142
143. 143
144. 144
145. 145
146. 146
147. 147
148. 148
149. 149
150. 150

// SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com>
//
// SPDX-License-Identifier: Apache-2.0

export interface FileSystemStats {
	contentUpdatedAt?: Date;
	createdAt?: Date;
}

export interface FileReader {
	readonly type: "file";
	readonly name: string;
	readonly path: readonly string[];
	readonly parent: DirectoryReader | RootDirectoryReader;

	read(): Promise<Uint8Array>;

	stat(): FileSystemStats | Promise<FileSystemStats>;
}

export interface DirectoryReader {
	readonly type: "directory";
	readonly name: string;
	readonly path: readonly string[];
	readonly parent: DirectoryReader | RootDirectoryReader;

	read(): Promise<ReadonlyArray<FileReader | DirectoryReader>>;

	stat(): FileSystemStats | Promise<FileSystemStats>;
}

export type DocumentToken = `mxt_${string}`;

export type AssetToken = `mxa_${string}`;

export interface RootDirectoryReader {
	readonly type: "root";

	read(): Promise<ReadonlyArray<FileReader | DirectoryReader>>;

	/**
	 * Returns a file at the path.
	 * This function may throw an error if the file not found.
	 */
	openFile(path: readonly string[]): Promise<FileReader> | FileReader;

	/**
	 * Returns a directory at the path.
	 * This function may throw an error if the directory not found.
	 */
	openDirectory(
		path: readonly string[],
	): Promise<DirectoryReader> | DirectoryReader;
}

export interface DocumentMetadata {
	/**
	 * An identifier for a document, unique among a directory the document belongs to.
	 */
	readonly name: string;

	/**
	 * Human-readable text representing a title of the *document*.
	 * Although there is no restriction on available characters, you should avoid using
	 * control characters.
	 * ([Unicode control characters - Wikipedia](https://en.wikipedia.org/wiki/Unicode_control_characters))
	 */
	readonly title: string;

	/**
	 * Language for a document directory or a document.
	 * If this is empty, Macana looks up the most closest document directory language set.
	 * If none of the ancestors have a language, Macana will use a user given default language.
	 */
	readonly language?: string;

	/**
	 * Whether this document is the default document for the entire document tree.
	 * The behavior of when multiple documents have this property set to true is undefined.
	 * This property does not take an effect for document tree.
	 */
	readonly isDefaultDocument?: boolean;

	/**
	 * Datetime when the document or the document directory created at.
	 */
	readonly createdAt?: Date;

	/**
	 * Datetime when the document or the document directory last updated at.
	 */
	readonly updatedAt?: Date;
}

export interface DocumentContent<
	Kind extends string = string,
	Content = unknown,
> {
	kind: Kind;
	content: Content;
}

export interface Document<Content extends DocumentContent = DocumentContent> {
	readonly type: "document";
	readonly metadata: DocumentMetadata;
	readonly file: FileReader;

	readonly content: Content;

	/**
	 * Document path: list of names, not file paths.
	 */
	readonly path: readonly string[];
}

export interface DocumentDirectory {
	readonly type: "directory";
	readonly metadata: DocumentMetadata;
	readonly directory: DirectoryReader;
	readonly entries: ReadonlyArray<Document | DocumentDirectory>;

	/**
	 * Document path: list of names, not file paths.
	 */
	readonly path: readonly string[];
}

export interface DocumentTree {
	readonly type: "tree";
	readonly nodes: ReadonlyArray<Document | DocumentDirectory>;

	readonly defaultLanguage: string;

	/**
	 * Representive, facade document.
	 */
	readonly defaultDocument: Document;

	/**
	 * Get a document in exchange for the token.
	 * Throws an error if the token is invalid or target document is missing.
	 */
	exchangeToken(token: DocumentToken): Document;

	/**
	 * Get an asset file in exchange for the token.
	 * Throws an error if the token is invalid or target file is missing.
	 */
	exchangeToken(token: AssetToken): FileReader;
}