@onlyworlds/sdk 4.108.1 → 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 +10 -0
- package/README.md +6 -0
- package/dist/index.d.ts +31 -3
- package/dist/index.js +39 -11
- 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,16 @@ 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
|
+
|
|
8
18
|
## [4.108.1] - 2026-10-29
|
|
9
19
|
|
|
10
20
|
### Fixed
|
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
|
@@ -5742,6 +5742,9 @@ declare function doorWhere(door: OwDoor): string;
|
|
|
5742
5742
|
* producers `records/RECORDS.json` marks private, left out whole unless the
|
|
5743
5743
|
* caller asks (OW-8, §4.5 rule 11). Element files marked hidden travel too,
|
|
5744
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`).
|
|
5745
5748
|
*
|
|
5746
5749
|
* A tool's own `.<tool>/` folder is the tool's (spec §4): the reader returns
|
|
5747
5750
|
* it like any file (a caller leaves files out with `skip`), and the writer
|
|
@@ -5804,6 +5807,16 @@ interface OwWriteWorldFileOptions {
|
|
|
5804
5807
|
* default is the opposite of `includePrivateRecords`'s on purpose.
|
|
5805
5808
|
*/
|
|
5806
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;
|
|
5807
5820
|
/** Called once with what the write left out, after the archive is made and before it is returned; never on a refusal. */
|
|
5808
5821
|
report?: (report: OwWriteWorldFileReport) => void;
|
|
5809
5822
|
}
|
|
@@ -5811,6 +5824,8 @@ interface OwWriteWorldFileOptions {
|
|
|
5811
5824
|
interface OwWriteWorldFileReport {
|
|
5812
5825
|
/** Element files left out for the hidden mark (`includeHidden: false`); 0 otherwise. */
|
|
5813
5826
|
hiddenLeftOut: number;
|
|
5827
|
+
/** Element files written without their author fields (the default); 0 with `includeAuthorFields: true`. */
|
|
5828
|
+
authorFieldsLeftOut: number;
|
|
5814
5829
|
}
|
|
5815
5830
|
/**
|
|
5816
5831
|
* Write a world file under one top-level folder `topDir`: the `mimetype`
|
|
@@ -5840,10 +5855,23 @@ interface OwWriteWorldFileReport {
|
|
|
5840
5855
|
* hidden one keeps its id, which then names no file. Pass
|
|
5841
5856
|
* `report: r => …` to learn `r.hiddenLeftOut`, the count left out.
|
|
5842
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
|
+
*
|
|
5843
5871
|
* Throws a `TypeError`, having written nothing, for an unknown option, an
|
|
5844
|
-
* `includePrivateRecords` or `
|
|
5845
|
-
* `report` that is not a function, and (unless private
|
|
5846
|
-
* 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
|
|
5847
5875
|
* marks an entry private without a producer name. Refuses (`OwWorldFileError`)
|
|
5848
5876
|
* an unsafe path or `topDir`, a duplicate path, a name some disk cannot hold,
|
|
5849
5877
|
* two names that fold to one, and a world.json that is missing, will not parse
|
package/dist/index.js
CHANGED
|
@@ -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
|
|