@onlyworlds/sdk 4.186.2 → 4.187.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +4 -2
- package/README.md +19 -0
- package/SCHEMA.md +1 -1
- package/dist/{chunk-EFH2PAJN.js → chunk-5XUVYQ5Q.js} +2 -650
- package/dist/chunk-EU4B5WYE.js +662 -0
- package/dist/chunk-OCPNZOFN.js +938 -0
- package/dist/convert.d.ts +200 -0
- package/dist/convert.js +2395 -0
- package/dist/index.js +110 -978
- package/dist/waymark.js +4 -2
- package/package.json +12 -5
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A world folder written in memory (OnlyWorlds Folder Format v0.3.24): `world.json` and one file
|
|
3
|
+
* per element under `elements/<type>/`, named `<slug>--<tail8>.json` (§3.2, the collision rule
|
|
4
|
+
* included), each the canonical bytes of §5 (`JSON.stringify(value, null, 2)` and a newline, UTF-8,
|
|
5
|
+
* keys in the order given). The same bytes as the Python package's `write_folder`: the filenames
|
|
6
|
+
* are its `slugify`, `id_tail` and `resolve_filenames`, the text its `_jsonfmt.encode`.
|
|
7
|
+
*
|
|
8
|
+
* Module-internal: not in the package's exports.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/** One file of a folder: its path inside the folder, `/`-separated, and its bytes. */
|
|
12
|
+
interface OwFolderFile {
|
|
13
|
+
path: string;
|
|
14
|
+
data: Uint8Array;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The shared core of the import doors: what every reader of another tool's export needs on the
|
|
19
|
+
* OnlyWorlds side, with no tool's keys in it. A reader (one per tool, its rules in code, its tables
|
|
20
|
+
* and wording as data) builds a `Draft` per element and hands the core what it found; the core
|
|
21
|
+
* holds the element's body in the schema's order with the hidden mark, the extension keys a value
|
|
22
|
+
* is kept under (named from the key, `_2` and on when taken), each kept key reported once, exact
|
|
23
|
+
* copies folded, the schema's field kinds and link targets, the Narrative and Relation fields for
|
|
24
|
+
* a linked type, the names the door made and their count, `world.json`, and the folder's files.
|
|
25
|
+
*
|
|
26
|
+
* Exported from `@onlyworlds/sdk/convert` are its findings' types; the rest is module-internal.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
/** A key, or an attribute, not placed on a field: kept on the element as `keptAs`. */
|
|
30
|
+
interface OwConvertUnplaced {
|
|
31
|
+
/** The element's name. */
|
|
32
|
+
element: string;
|
|
33
|
+
key: string;
|
|
34
|
+
why: string;
|
|
35
|
+
keptAs: string;
|
|
36
|
+
}
|
|
37
|
+
/** A link or mention whose target is not an element of the folder. */
|
|
38
|
+
interface OwConvertUnresolved {
|
|
39
|
+
element: string;
|
|
40
|
+
/** Where on the element: `parent`, `mention`, a key of the export. */
|
|
41
|
+
where: string;
|
|
42
|
+
/** The target as the export writes it. */
|
|
43
|
+
target: string;
|
|
44
|
+
why: string;
|
|
45
|
+
}
|
|
46
|
+
/** Exact copies on one element folded into one. */
|
|
47
|
+
interface OwConvertFolded {
|
|
48
|
+
element: string;
|
|
49
|
+
/** What was copied: `post`, `trait`, `relationship`, ... */
|
|
50
|
+
what: string;
|
|
51
|
+
name: string;
|
|
52
|
+
copies: number;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* One kind of name a door makes, for a thing the export never names or leaves unnamed. `type` is
|
|
56
|
+
* the element type it names, or `*` for any. `pattern` is its human form (the export's words in
|
|
57
|
+
* angle brackets); `regex` matches a whole name of the kind.
|
|
58
|
+
*/
|
|
59
|
+
interface OwConvertMadeName {
|
|
60
|
+
kind: string;
|
|
61
|
+
type: string;
|
|
62
|
+
pattern: string;
|
|
63
|
+
source: 'joined' | 'ours';
|
|
64
|
+
regex: string;
|
|
65
|
+
}
|
|
66
|
+
/** A made-name record's `type` for a name given to an element of whatever type it became. */
|
|
67
|
+
declare const ANY_TYPE = "*";
|
|
68
|
+
/** The folder format's `producer` line: the tool that made the folder and its version. */
|
|
69
|
+
interface OwConvertProducer {
|
|
70
|
+
tool: string;
|
|
71
|
+
version?: string;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Kanka's reader: a Kanka JSON export (the zip "Export the campaign" gives) as a world folder,
|
|
76
|
+
* the same folder as the Python package's door (`python -m onlyworlds.kanka`) byte for byte, and
|
|
77
|
+
* the same report. Its rules are this file; its tables (Kanka's folders to element types, its keys
|
|
78
|
+
* to fields, the fixed key lists, the names it makes) and every line of its report are
|
|
79
|
+
* `kanka.json`, the same bytes the Python door reads. The Python module's docstring is the long
|
|
80
|
+
* account of what becomes what; in short:
|
|
81
|
+
*
|
|
82
|
+
* - each entity an element of its module's type (a module with no type a Narrative, supertype
|
|
83
|
+
* `Article`), its entry and visible posts the description (a Narrative's story), its parent,
|
|
84
|
+
* places, kin, kind and memberships links, an attribute named like a field that field when the
|
|
85
|
+
* value fits, every other key kept as `x_kanka_<key>` and reported;
|
|
86
|
+
* - relationships as Relations (a two-way pair as one), a tag's Narrative linking what carries it;
|
|
87
|
+
* - what Kanka hides imported carrying `hidden: true`, never dropped and never public: a private
|
|
88
|
+
* entity whole, a post not visible to all as its own Narrative, a relationship hidden on a side,
|
|
89
|
+
* and on a visible entity its private details in one hidden Narrative;
|
|
90
|
+
* - exact duplicates folded into one; ids UUIDv5 of the campaign and Kanka's ids, so the same
|
|
91
|
+
* export twice gives the same folder.
|
|
92
|
+
*/
|
|
93
|
+
|
|
94
|
+
/** The names this door makes, one record a kind, each kind counted in the report. */
|
|
95
|
+
declare const KANKA_MADE_NAMES: readonly OwConvertMadeName[];
|
|
96
|
+
/** One export folder and what its entities became. */
|
|
97
|
+
interface OwKankaModule {
|
|
98
|
+
folder: string;
|
|
99
|
+
type: string;
|
|
100
|
+
entities: number;
|
|
101
|
+
/** `proven` (read on a real export), `believed`, or `untyped` (Narratives, supertype `Article`). */
|
|
102
|
+
status: 'proven' | 'believed' | 'untyped';
|
|
103
|
+
}
|
|
104
|
+
/** An entity's picture, named on its element as `x_kanka_image` but not imported. */
|
|
105
|
+
interface OwKankaPicture {
|
|
106
|
+
element: string;
|
|
107
|
+
uuid: string;
|
|
108
|
+
/** The upload's file in the export (`gallery/<uuid>.<ext>`); null when `gallery/` has no such upload. */
|
|
109
|
+
path: string | null;
|
|
110
|
+
/** The upload's own file name; null when there is none. */
|
|
111
|
+
original: string | null;
|
|
112
|
+
/** The upload is not visible to all and the element is: the uuid is kept alone. */
|
|
113
|
+
private: boolean;
|
|
114
|
+
}
|
|
115
|
+
/** An element that carries a tag the tag's Narrative does not link. */
|
|
116
|
+
interface OwKankaUntagged {
|
|
117
|
+
tag: string;
|
|
118
|
+
element: string;
|
|
119
|
+
why: string;
|
|
120
|
+
}
|
|
121
|
+
/** What the source hides, imported carrying `hidden: true`: never dropped, never public. */
|
|
122
|
+
interface OwKankaHidden {
|
|
123
|
+
/** Entities marked private: elements carrying the mark. */
|
|
124
|
+
entities: number;
|
|
125
|
+
/** Posts not visible to all on a visible entity: each its own hidden Narrative. */
|
|
126
|
+
posts: number;
|
|
127
|
+
/** Relationships hidden on a side, or touching a hidden entity: hidden Relations. */
|
|
128
|
+
relationships: number;
|
|
129
|
+
/** On a visible entity, held in its hidden-details Narrative. */
|
|
130
|
+
traits: number;
|
|
131
|
+
personality: number;
|
|
132
|
+
attributes: number;
|
|
133
|
+
links: number;
|
|
134
|
+
/** Hidden-details Narratives made. */
|
|
135
|
+
details: number;
|
|
136
|
+
}
|
|
137
|
+
/** The report of one conversion: the Python door's report, field for field, and its text. */
|
|
138
|
+
interface OwKankaReport {
|
|
139
|
+
/** The export as the report names it (the `source` option). */
|
|
140
|
+
source: string;
|
|
141
|
+
/** The world's name, as `world.json` has it. */
|
|
142
|
+
worldName: string;
|
|
143
|
+
/** Elements written, by type, in code point order of the type. */
|
|
144
|
+
counts: Record<string, number>;
|
|
145
|
+
total: number;
|
|
146
|
+
modules: OwKankaModule[];
|
|
147
|
+
/** Relation elements made, by the relation's text, in the order of the text. */
|
|
148
|
+
relations: {
|
|
149
|
+
text: string;
|
|
150
|
+
count: number;
|
|
151
|
+
}[];
|
|
152
|
+
folded: OwConvertFolded[];
|
|
153
|
+
unplaced: OwConvertUnplaced[];
|
|
154
|
+
unresolved: OwConvertUnresolved[];
|
|
155
|
+
hidden: OwKankaHidden;
|
|
156
|
+
/** Names of the entities made within seconds of the campaign, Kanka's starter content perhaps (imported all the same). */
|
|
157
|
+
possiblyStarter: string[];
|
|
158
|
+
/** Uploads read in `gallery/`, and how many an entity names. */
|
|
159
|
+
uploads: number;
|
|
160
|
+
uploadsNamed: number;
|
|
161
|
+
pictures: OwKankaPicture[];
|
|
162
|
+
untagged: OwKankaUntagged[];
|
|
163
|
+
/** Names made here, not taken whole from the export: a kind of `KANKA_MADE_NAMES` -> its elements, in declared order. */
|
|
164
|
+
madeNames: Record<string, number>;
|
|
165
|
+
notes: string[];
|
|
166
|
+
/** The report's lines, as the Python door prints them, but its last (`kankaReportText` adds it). */
|
|
167
|
+
lines: string[];
|
|
168
|
+
}
|
|
169
|
+
/** A conversion: the world folder's files, in code point order of their paths, and the report. */
|
|
170
|
+
interface OwKankaConversion {
|
|
171
|
+
files: OwFolderFile[];
|
|
172
|
+
report: OwKankaReport;
|
|
173
|
+
}
|
|
174
|
+
interface OwConvertKankaOptions {
|
|
175
|
+
/** How the report names the export (the Python door prints the path it was given). Default `export.zip`. */
|
|
176
|
+
source?: string;
|
|
177
|
+
/** The tool `world.json`'s `producer` line names, and its version. Default this package and its version, `{ tool: '@onlyworlds/sdk', version: '<the installed version>' }`. */
|
|
178
|
+
producer?: OwConvertProducer;
|
|
179
|
+
}
|
|
180
|
+
/** Why an export was refused, nothing returned: `not_a_zip`, or `not_an_export` (no `campaign.json` with an id). */
|
|
181
|
+
type OwConvertErrorReason = 'not_a_zip' | 'not_an_export';
|
|
182
|
+
/** An export was refused; the message is the Python door's. */
|
|
183
|
+
declare class OwConvertError extends Error {
|
|
184
|
+
readonly reason: OwConvertErrorReason;
|
|
185
|
+
constructor(reason: OwConvertErrorReason, message: string);
|
|
186
|
+
}
|
|
187
|
+
/** The report's whole text, as the Python door prints it: its lines, then where it was written (`out`), or that it was a plan (null). */
|
|
188
|
+
declare function kankaReportText(report: OwKankaReport, out: string | null): string;
|
|
189
|
+
/**
|
|
190
|
+
* Read a Kanka JSON export (the zip's bytes) into a world folder, in memory: its files and the
|
|
191
|
+
* report. Nothing is written; the caller writes `files` under a new folder. The same folder as the
|
|
192
|
+
* Python package's door byte for byte, given the same `producer`. What Kanka hides comes in
|
|
193
|
+
* carrying `hidden: true`, counted in the report. Throws `OwConvertError` for bytes that are not a
|
|
194
|
+
* zip or an export with no `campaign.json`, and a `TypeError` for an unknown option, before anything
|
|
195
|
+
* is read.
|
|
196
|
+
*/
|
|
197
|
+
declare function convertKanka(bytes: Uint8Array, opts?: OwConvertKankaOptions): OwKankaConversion;
|
|
198
|
+
|
|
199
|
+
export { ANY_TYPE, KANKA_MADE_NAMES, OwConvertError, convertKanka, kankaReportText };
|
|
200
|
+
export type { OwConvertErrorReason, OwConvertFolded, OwConvertKankaOptions, OwConvertMadeName, OwConvertProducer, OwConvertUnplaced, OwConvertUnresolved, OwFolderFile, OwKankaConversion, OwKankaHidden, OwKankaModule, OwKankaPicture, OwKankaReport, OwKankaUntagged };
|