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

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

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

	read(): Promise<Uint8Array>;
}

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

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

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;
}

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;
}

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;
}