@onlyworlds/sdk 4.108.0 → 4.109.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 +7 -3
- package/CHANGELOG.md +16 -0
- package/README.md +6 -0
- package/dist/index.d.ts +38 -6
- package/dist/index.js +42 -14
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -115,9 +115,13 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
|
|
|
115
115
|
`writeWorldFile(files, topDir, { includePrivateRecords: true })` (since 4.63.0; OW-8).
|
|
116
116
|
Element files marked `hidden: true` travel by default (a copy); a share passes
|
|
117
117
|
`{ includeHidden: false, report: r => r.hiddenLeftOut }` to leave them out whole and count
|
|
118
|
-
them (since 4.70.0; §4.8).
|
|
119
|
-
|
|
120
|
-
|
|
118
|
+
them (since 4.70.0; §4.8). Element files leave out the author fields (`created_by`,
|
|
119
|
+
`changed_by`, `changed_via`, `changed_client`, `doors`: which member and tool wrote it) by default,
|
|
120
|
+
counted in `r.authorFieldsLeftOut`; `{ includeAuthorFields: true }` writes every file byte
|
|
121
|
+
for byte, for an archive of your own world (since 4.109.0). Two names are one after OW-18's
|
|
122
|
+
fold: NFC, then simple case folding, both Unicode 15.1's from its own files (`nfc` since
|
|
123
|
+
4.71.0, `simpleCaseFold`), never the runtime's `normalize`, whose Unicode is its ICU's (Node
|
|
124
|
+
22: 16.0).
|
|
121
125
|
- World calendars (since 4.20.0): `worldCalendars(elements)` finds the elements carrying
|
|
122
126
|
`atlas_calendar` (Atlas owns the field: read it, never write it); `resolveCalendar` picks
|
|
123
127
|
one; `formatStep(config, step)` names a point on the world's integer time line, `parseDate`
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,22 @@ earlier history lives in git log only.
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [4.109.0] - 2026-10-29
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- **`writeWorldFile` leaves the author fields out of every element file by default.** `created_by`, `changed_by`, `changed_via`, `changed_client` and `doors` record which member and which tool wrote each element (a membership id, a door), which means nothing to someone the world is handed to. Each element file under `elements/<type>/` or `spatial/<type>/` holding any of the five is now written without them, in the folder's own form (two-space indent, a trailing newline, its other keys in their order); `created_at` and `updated_at` stay. A file holding none of them, or that is not a JSON object, travels byte for byte, and `world.json`, records, media and every other file are untouched; an `x_*` value that holds one of the names is the extension's and stays. A caller archiving their own world passes `{ includeAuthorFields: true }`, which writes the same bytes as 4.108.1.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **`includeAuthorFields`** on `writeWorldFile`, refused by name when it is not a boolean, as `includePrivateRecords` and `includeHidden` are; and **`authorFieldsLeftOut`** in its `report`, the element files written without their author fields (0 when the option is true). A shared fixture of five cases (`test/fixtures/author-fields.fixture.json`, the same bytes as the Python package's) holds both writers to the same entries.
|
|
17
|
+
|
|
18
|
+
## [4.108.1] - 2026-10-29
|
|
19
|
+
|
|
20
|
+
### Fixed
|
|
21
|
+
|
|
22
|
+
- **A list filter with an empty value is sent.** `list` and `listAll` sent nothing for a key under `filter` whose value was `''`, so `filter: { characters: '' }` or `filter: { supertype: '' }` listed every element. On keel an empty value is a filter of its own: `supertype=` and `subtype=` list the elements with none, `characters=` the Messages addressed to everyone, and a single link's (`parent_location=`, since every single link became a list filter) the elements linking to nothing. Each key under `filter` is now sent as given, `''` included; an empty `name__icontains` still matches every name, and outside `filter` an empty value is still not sent. The `filter` doc names the single-link filters.
|
|
23
|
+
|
|
8
24
|
## [4.108.0] - 2026-10-29
|
|
9
25
|
|
|
10
26
|
### Added
|
package/README.md
CHANGED
|
@@ -320,6 +320,12 @@ const share = writeWorldFile(files, topDir, { includeHidden: false, report: r =>
|
|
|
320
320
|
|
|
321
321
|
The two defaults differ on purpose: private records stay out unless you ask, hidden elements stay in unless the write is a share.
|
|
322
322
|
|
|
323
|
+
An element's author fields, `created_by`, `changed_by`, `changed_via`, `changed_client` and `doors`, record which member and which tool wrote it (a membership id, a door), which means nothing to someone the world is handed to. So by default every element file leaves them out (since 4.109.0). `created_at` and `updated_at` stay. A file holding any of the five is rewritten without them, two-space indented with a trailing newline and its other keys in their order; a file holding none travels byte for byte, and nothing outside `elements/<type>/` (or `spatial/<type>/`) changes. `report` counts the files rewritten in `r.authorFieldsLeftOut`. To archive your own world as it is on disk, pass `includeAuthorFields: true`:
|
|
324
|
+
|
|
325
|
+
```typescript
|
|
326
|
+
const backup = writeWorldFile(files, topDir, { includeAuthorFields: true }); // every file byte for byte
|
|
327
|
+
```
|
|
328
|
+
|
|
323
329
|
## World calendars
|
|
324
330
|
|
|
325
331
|
A world's time is an integer line (`time_range_current` is a point on it, and so is an Event's `start_date`). A calendar names its points: months, days, eras. Atlas keeps a calendar on an element (a Construct by convention) in its `atlas_calendar` field, and the SDK reads it with Atlas's own calendar code (since 4.20.0). Atlas owns that field and is its only writer; read it, never write it.
|
package/dist/index.d.ts
CHANGED
|
@@ -3409,10 +3409,14 @@ interface ListParams {
|
|
|
3409
3409
|
/** Sparse include-set of field names. */
|
|
3410
3410
|
fields?: string[];
|
|
3411
3411
|
/**
|
|
3412
|
-
* Accepted: `name` (exact), `name__icontains`, `supertype`, `subtype`,
|
|
3412
|
+
* Accepted: `name` (exact), `name__icontains`, `supertype`, `subtype`,
|
|
3413
3413
|
* `characters=<id>` (contains) on every type with a `characters` link (at schema
|
|
3414
|
-
* 0.30.1: collective, construct, event, narrative, relation, title)
|
|
3415
|
-
*
|
|
3414
|
+
* 0.30.1: collective, construct, event, narrative, relation, title), and each single link
|
|
3415
|
+
* of the type (`parent_location`, `birthplace`, ...: the elements linking to that id). An
|
|
3416
|
+
* empty value is sent as `key=`, a filter of its own: `supertype: ''` lists the elements
|
|
3417
|
+
* with none, `characters: ''` a Message to everyone, a single link's the elements linking
|
|
3418
|
+
* to nothing (until 4.108.1 it was dropped and the list came back whole). Any other key
|
|
3419
|
+
* 422s server-side with the list of filters in the message -- the client passes keys
|
|
3416
3420
|
* through unchecked and lets the platform say so. (`__in`, `__gte`, `__lte` and
|
|
3417
3421
|
* `__isnull` are designed in keel's spec but not built; `ordering` 422s too.)
|
|
3418
3422
|
*/
|
|
@@ -5738,6 +5742,9 @@ declare function doorWhere(door: OwDoor): string;
|
|
|
5738
5742
|
* producers `records/RECORDS.json` marks private, left out whole unless the
|
|
5739
5743
|
* caller asks (OW-8, §4.5 rule 11). Element files marked hidden travel too,
|
|
5740
5744
|
* unless the caller says the file is a share (`includeHidden: false`, §4.8).
|
|
5745
|
+
* Element files leave out the five author fields, which record which member
|
|
5746
|
+
* and which tool wrote each element, unless the caller asks
|
|
5747
|
+
* (`includeAuthorFields`).
|
|
5741
5748
|
*
|
|
5742
5749
|
* A tool's own `.<tool>/` folder is the tool's (spec §4): the reader returns
|
|
5743
5750
|
* it like any file (a caller leaves files out with `skip`), and the writer
|
|
@@ -5800,6 +5807,16 @@ interface OwWriteWorldFileOptions {
|
|
|
5800
5807
|
* default is the opposite of `includePrivateRecords`'s on purpose.
|
|
5801
5808
|
*/
|
|
5802
5809
|
includeHidden?: boolean;
|
|
5810
|
+
/**
|
|
5811
|
+
* Carry the author fields of every element file: `created_by`,
|
|
5812
|
+
* `changed_by`, `changed_via`, `changed_client` and `doors`, which record
|
|
5813
|
+
* which member and which tool wrote it (a membership id, a door) and mean
|
|
5814
|
+
* nothing to someone the world is handed to. Left out or false, each
|
|
5815
|
+
* element file holding any of the five is rewritten without them
|
|
5816
|
+
* (two-space indent, a trailing newline, the other keys in their order),
|
|
5817
|
+
* and `report` counts them. Pass true for a byte copy of your own folder.
|
|
5818
|
+
*/
|
|
5819
|
+
includeAuthorFields?: boolean;
|
|
5803
5820
|
/** Called once with what the write left out, after the archive is made and before it is returned; never on a refusal. */
|
|
5804
5821
|
report?: (report: OwWriteWorldFileReport) => void;
|
|
5805
5822
|
}
|
|
@@ -5807,6 +5824,8 @@ interface OwWriteWorldFileOptions {
|
|
|
5807
5824
|
interface OwWriteWorldFileReport {
|
|
5808
5825
|
/** Element files left out for the hidden mark (`includeHidden: false`); 0 otherwise. */
|
|
5809
5826
|
hiddenLeftOut: number;
|
|
5827
|
+
/** Element files written without their author fields (the default); 0 with `includeAuthorFields: true`. */
|
|
5828
|
+
authorFieldsLeftOut: number;
|
|
5810
5829
|
}
|
|
5811
5830
|
/**
|
|
5812
5831
|
* Write a world file under one top-level folder `topDir`: the `mimetype`
|
|
@@ -5836,10 +5855,23 @@ interface OwWriteWorldFileReport {
|
|
|
5836
5855
|
* hidden one keeps its id, which then names no file. Pass
|
|
5837
5856
|
* `report: r => …` to learn `r.hiddenLeftOut`, the count left out.
|
|
5838
5857
|
*
|
|
5858
|
+
* The author fields, `created_by`, `changed_by`, `changed_via`,
|
|
5859
|
+
* `changed_client` and `doors`, record which member and which tool wrote
|
|
5860
|
+
* each element (a membership id, a door), which means nothing to someone the
|
|
5861
|
+
* world is handed to. So by default every element file under
|
|
5862
|
+
* `elements/<type>/` or `spatial/<type>/` leaves them out; `created_at` and
|
|
5863
|
+
* `updated_at` stay. A file holding any of them is
|
|
5864
|
+
* rewritten without them in the folder's own form (two-space indent, a
|
|
5865
|
+
* trailing newline, the other keys in their order); one holding none, or
|
|
5866
|
+
* that is not a JSON object, travels byte for byte, and nothing outside the
|
|
5867
|
+
* element files is touched. `r.authorFieldsLeftOut` counts the files
|
|
5868
|
+
* rewritten. Pass `{ includeAuthorFields: true }` for a byte copy of your own
|
|
5869
|
+
* folder, as an archive of your own world.
|
|
5870
|
+
*
|
|
5839
5871
|
* Throws a `TypeError`, having written nothing, for an unknown option, an
|
|
5840
|
-
* `includePrivateRecords` or `
|
|
5841
|
-
* `report` that is not a function, and (unless private
|
|
5842
|
-
* are asked for) a `RECORDS.json` that is not a JSON array of objects or that
|
|
5872
|
+
* `includePrivateRecords`, `includeHidden` or `includeAuthorFields` that is
|
|
5873
|
+
* not a boolean, a `report` that is not a function, and (unless private
|
|
5874
|
+
* records are asked for) a `RECORDS.json` that is not a JSON array of objects or that
|
|
5843
5875
|
* marks an entry private without a producer name. Refuses (`OwWorldFileError`)
|
|
5844
5876
|
* an unsafe path or `topDir`, a duplicate path, a name some disk cannot hold,
|
|
5845
5877
|
* two names that fold to one, and a world.json that is missing, will not parse
|
package/dist/index.js
CHANGED
|
@@ -827,7 +827,7 @@ var OwV2Client = class {
|
|
|
827
827
|
created_by: params.createdBy,
|
|
828
828
|
...params.filter,
|
|
829
829
|
as: params.viewAs
|
|
830
|
-
});
|
|
830
|
+
}, new Set(Object.keys(params.filter ?? {})));
|
|
831
831
|
return this.request("GET", `/${type}/`, { query, worldRead: true, ...withSignal(params.signal) });
|
|
832
832
|
}
|
|
833
833
|
async draught(characterId, policy = {}) {
|
|
@@ -2301,10 +2301,10 @@ function clientNameOf(value) {
|
|
|
2301
2301
|
}
|
|
2302
2302
|
return value;
|
|
2303
2303
|
}
|
|
2304
|
-
function buildQuery(params) {
|
|
2304
|
+
function buildQuery(params, keepEmpty) {
|
|
2305
2305
|
const q = new URLSearchParams();
|
|
2306
2306
|
for (const [k, v] of Object.entries(params)) {
|
|
2307
|
-
if (v !== void 0 && v !== null && v !== "") q.set(k, String(v));
|
|
2307
|
+
if (v !== void 0 && v !== null && (v !== "" || keepEmpty?.has(k))) q.set(k, String(v));
|
|
2308
2308
|
}
|
|
2309
2309
|
return q.toString();
|
|
2310
2310
|
}
|
|
@@ -3769,14 +3769,15 @@ function carried(path) {
|
|
|
3769
3769
|
return !segs.some((s) => s.startsWith(".")) && !path.endsWith(".meta");
|
|
3770
3770
|
}
|
|
3771
3771
|
var STAMP = new Date(1980, 0, 1, 0, 0, 0);
|
|
3772
|
-
var WRITE_OPTION_KEYS = ["includePrivateRecords", "includeHidden", "report"];
|
|
3772
|
+
var WRITE_OPTION_KEYS = ["includePrivateRecords", "includeHidden", "includeAuthorFields", "report"];
|
|
3773
3773
|
var RECORDS_MANIFEST = "records/RECORDS.json";
|
|
3774
|
+
var AUTHOR_FIELDS = ["created_by", "changed_by", "changed_via", "changed_client", "doors"];
|
|
3774
3775
|
function writeOptions(opts) {
|
|
3775
|
-
if (opts === void 0 || opts === null) return { includePrivate: false, includeHidden: true };
|
|
3776
|
+
if (opts === void 0 || opts === null) return { includePrivate: false, includeHidden: true, includeAuthorFields: false };
|
|
3776
3777
|
if (typeof opts !== "object") throw new TypeError(`writeWorldFile: options must be an object, such as { includePrivateRecords: true }. Nothing was written.`);
|
|
3777
3778
|
refuseUnknownOptions("writeWorldFile", opts, WRITE_OPTION_KEYS, "Nothing was written.");
|
|
3778
3779
|
const o = opts;
|
|
3779
|
-
for (const key of ["includePrivateRecords", "includeHidden"]) {
|
|
3780
|
+
for (const key of ["includePrivateRecords", "includeHidden", "includeAuthorFields"]) {
|
|
3780
3781
|
const asked = o[key];
|
|
3781
3782
|
if (asked !== void 0 && typeof asked !== "boolean") {
|
|
3782
3783
|
throw new TypeError(`writeWorldFile: ${key} must be true or false; got ${JSON.stringify(asked) ?? String(asked)}. Nothing was written.`);
|
|
@@ -3785,21 +3786,39 @@ function writeOptions(opts) {
|
|
|
3785
3786
|
if (o.report !== void 0 && typeof o.report !== "function") {
|
|
3786
3787
|
throw new TypeError(`writeWorldFile: report must be a function; got ${JSON.stringify(o.report) ?? String(o.report)}. Nothing was written.`);
|
|
3787
3788
|
}
|
|
3788
|
-
return {
|
|
3789
|
+
return {
|
|
3790
|
+
includePrivate: o.includePrivateRecords === true,
|
|
3791
|
+
includeHidden: o.includeHidden !== false,
|
|
3792
|
+
includeAuthorFields: o.includeAuthorFields === true,
|
|
3793
|
+
report: o.report
|
|
3794
|
+
};
|
|
3789
3795
|
}
|
|
3790
|
-
function
|
|
3796
|
+
function elementObject(f) {
|
|
3791
3797
|
const segs = f.path.split("/");
|
|
3792
|
-
if (segs.length !== 3 || segs[0] !== "elements" && segs[0] !== "spatial" || !/\.json$/i.test(segs[2])) return
|
|
3798
|
+
if (segs.length !== 3 || segs[0] !== "elements" && segs[0] !== "spatial" || !/\.json$/i.test(segs[2])) return null;
|
|
3793
3799
|
let doc;
|
|
3794
3800
|
try {
|
|
3795
3801
|
doc = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(f.data));
|
|
3796
3802
|
} catch {
|
|
3797
|
-
return
|
|
3803
|
+
return null;
|
|
3798
3804
|
}
|
|
3799
|
-
if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return
|
|
3805
|
+
if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return null;
|
|
3806
|
+
return doc;
|
|
3807
|
+
}
|
|
3808
|
+
function isHiddenElement(f) {
|
|
3809
|
+
const doc = elementObject(f);
|
|
3810
|
+
if (!doc) return false;
|
|
3800
3811
|
const mark = doc.hidden;
|
|
3801
3812
|
return mark !== void 0 && mark !== null && mark !== false;
|
|
3802
3813
|
}
|
|
3814
|
+
function withoutAuthorFields(f) {
|
|
3815
|
+
const doc = elementObject(f);
|
|
3816
|
+
if (!doc) return null;
|
|
3817
|
+
const present = AUTHOR_FIELDS.filter((k) => k in doc);
|
|
3818
|
+
if (!present.length) return null;
|
|
3819
|
+
for (const k of present) delete doc[k];
|
|
3820
|
+
return new TextEncoder().encode(JSON.stringify(doc, null, 2) + "\n");
|
|
3821
|
+
}
|
|
3803
3822
|
function privateProducers(files) {
|
|
3804
3823
|
const manifest = files.find((f) => f.path === RECORDS_MANIFEST);
|
|
3805
3824
|
if (!manifest) return [];
|
|
@@ -3824,7 +3843,7 @@ function privateProducers(files) {
|
|
|
3824
3843
|
return out;
|
|
3825
3844
|
}
|
|
3826
3845
|
function writeWorldFile(files, topDir, opts = {}) {
|
|
3827
|
-
const { includePrivate, includeHidden, report } = writeOptions(opts);
|
|
3846
|
+
const { includePrivate, includeHidden, includeAuthorFields, report } = writeOptions(opts);
|
|
3828
3847
|
if (pathFault(topDir) || topDir.includes("/")) throw new OwWorldFileError("unsafe_path");
|
|
3829
3848
|
const seen = /* @__PURE__ */ new Set();
|
|
3830
3849
|
for (const f of files) {
|
|
@@ -3857,13 +3876,22 @@ function writeWorldFile(files, topDir, opts = {}) {
|
|
|
3857
3876
|
const input = {
|
|
3858
3877
|
[MARKER_NAME]: [new TextEncoder().encode(WORLD_FILE_MEDIA_TYPE), { level: 0, mtime: STAMP }]
|
|
3859
3878
|
};
|
|
3879
|
+
let authorFieldsLeftOut = 0;
|
|
3860
3880
|
for (const f of [...kept].sort((a, b) => byCodePoint(a.path, b.path))) {
|
|
3861
3881
|
let data = f.data;
|
|
3862
|
-
if (f.path === WORLD_FILE)
|
|
3882
|
+
if (f.path === WORLD_FILE) {
|
|
3883
|
+
data = withoutLink(data, parseWorld(data)).data;
|
|
3884
|
+
} else if (!includeAuthorFields) {
|
|
3885
|
+
const bare = withoutAuthorFields(f);
|
|
3886
|
+
if (bare) {
|
|
3887
|
+
data = bare;
|
|
3888
|
+
authorFieldsLeftOut++;
|
|
3889
|
+
}
|
|
3890
|
+
}
|
|
3863
3891
|
input[`${topDir}/${f.path}`] = [data, { level: /\.json$/i.test(f.path) ? 6 : 0, mtime: STAMP }];
|
|
3864
3892
|
}
|
|
3865
3893
|
const zip = zipSync(input);
|
|
3866
|
-
report?.({ hiddenLeftOut });
|
|
3894
|
+
report?.({ hiddenLeftOut, authorFieldsLeftOut });
|
|
3867
3895
|
return zip;
|
|
3868
3896
|
}
|
|
3869
3897
|
|