@onlyworlds/sdk 4.108.1 → 4.110.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 +35 -5
- package/dist/index.js +40 -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,22 @@ earlier history lives in git log only.
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [4.110.0] - 2026-10-30
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- **`openersFor` checks the whole address.** It handed the address writer only the world, type and id, in the site's form, so a malformed `lens` or `moment`, or a `form` that is neither `human` nor `text`, still gave rows. The whole address now goes to `elementAddress` in its own form (the site's when it has none), so it refuses with the writer's own `OwAddressError`, `bad_lens`, `bad_moment` or `bad_form`, as it already did for the world, type and id; an address without a world still refuses `no_world`, the text form inside a world included. The rows are unchanged: a lens and a moment still ride on no href. The shared fixture gains four cases (45; the same bytes as the Python package's): the three refusals, and a well-formed lens and moment giving exactly the rows of the same address without them.
|
|
13
|
+
|
|
14
|
+
## [4.109.0] - 2026-10-29
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
- **`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.
|
|
19
|
+
|
|
20
|
+
### Added
|
|
21
|
+
|
|
22
|
+
- **`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.
|
|
23
|
+
|
|
8
24
|
## [4.108.1] - 2026-10-29
|
|
9
25
|
|
|
10
26
|
### 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
|
@@ -5631,8 +5631,10 @@ interface OwOpener {
|
|
|
5631
5631
|
* only when the surface knows it is true), `device` on a phone "Needs the world on this phone"; then
|
|
5632
5632
|
* "Opens the world" (a world door on an element: a sign-in the row needs is the more urgent word); else null.
|
|
5633
5633
|
*
|
|
5634
|
-
* Refuses with `OwAddressError`
|
|
5635
|
-
*
|
|
5634
|
+
* Refuses with `OwAddressError` whatever `elementAddress` refuses of the whole address, in its own form
|
|
5635
|
+
* (the site's when it has none): a form, type, id, pairing, moment or lens (`bad_moment`, `bad_lens`),
|
|
5636
|
+
* and a slug or anything else for the world's id (`bad_world`); and an address without a world
|
|
5637
|
+
* (`no_world`), the text form inside a world included, since every row needs one. A TypeError names the
|
|
5636
5638
|
* rest: a `kind` that is neither, an element's openers asked of an address with no element, an unknown
|
|
5637
5639
|
* key on the address or the surface, a missing or unknown `audience`, a surface value of the wrong type,
|
|
5638
5640
|
* a tools row that is not one (a `needs` outside the list's format included).
|
|
@@ -5742,6 +5744,9 @@ declare function doorWhere(door: OwDoor): string;
|
|
|
5742
5744
|
* producers `records/RECORDS.json` marks private, left out whole unless the
|
|
5743
5745
|
* caller asks (OW-8, §4.5 rule 11). Element files marked hidden travel too,
|
|
5744
5746
|
* unless the caller says the file is a share (`includeHidden: false`, §4.8).
|
|
5747
|
+
* Element files leave out the five author fields, which record which member
|
|
5748
|
+
* and which tool wrote each element, unless the caller asks
|
|
5749
|
+
* (`includeAuthorFields`).
|
|
5745
5750
|
*
|
|
5746
5751
|
* A tool's own `.<tool>/` folder is the tool's (spec §4): the reader returns
|
|
5747
5752
|
* it like any file (a caller leaves files out with `skip`), and the writer
|
|
@@ -5804,6 +5809,16 @@ interface OwWriteWorldFileOptions {
|
|
|
5804
5809
|
* default is the opposite of `includePrivateRecords`'s on purpose.
|
|
5805
5810
|
*/
|
|
5806
5811
|
includeHidden?: boolean;
|
|
5812
|
+
/**
|
|
5813
|
+
* Carry the author fields of every element file: `created_by`,
|
|
5814
|
+
* `changed_by`, `changed_via`, `changed_client` and `doors`, which record
|
|
5815
|
+
* which member and which tool wrote it (a membership id, a door) and mean
|
|
5816
|
+
* nothing to someone the world is handed to. Left out or false, each
|
|
5817
|
+
* element file holding any of the five is rewritten without them
|
|
5818
|
+
* (two-space indent, a trailing newline, the other keys in their order),
|
|
5819
|
+
* and `report` counts them. Pass true for a byte copy of your own folder.
|
|
5820
|
+
*/
|
|
5821
|
+
includeAuthorFields?: boolean;
|
|
5807
5822
|
/** Called once with what the write left out, after the archive is made and before it is returned; never on a refusal. */
|
|
5808
5823
|
report?: (report: OwWriteWorldFileReport) => void;
|
|
5809
5824
|
}
|
|
@@ -5811,6 +5826,8 @@ interface OwWriteWorldFileOptions {
|
|
|
5811
5826
|
interface OwWriteWorldFileReport {
|
|
5812
5827
|
/** Element files left out for the hidden mark (`includeHidden: false`); 0 otherwise. */
|
|
5813
5828
|
hiddenLeftOut: number;
|
|
5829
|
+
/** Element files written without their author fields (the default); 0 with `includeAuthorFields: true`. */
|
|
5830
|
+
authorFieldsLeftOut: number;
|
|
5814
5831
|
}
|
|
5815
5832
|
/**
|
|
5816
5833
|
* Write a world file under one top-level folder `topDir`: the `mimetype`
|
|
@@ -5840,10 +5857,23 @@ interface OwWriteWorldFileReport {
|
|
|
5840
5857
|
* hidden one keeps its id, which then names no file. Pass
|
|
5841
5858
|
* `report: r => …` to learn `r.hiddenLeftOut`, the count left out.
|
|
5842
5859
|
*
|
|
5860
|
+
* The author fields, `created_by`, `changed_by`, `changed_via`,
|
|
5861
|
+
* `changed_client` and `doors`, record which member and which tool wrote
|
|
5862
|
+
* each element (a membership id, a door), which means nothing to someone the
|
|
5863
|
+
* world is handed to. So by default every element file under
|
|
5864
|
+
* `elements/<type>/` or `spatial/<type>/` leaves them out; `created_at` and
|
|
5865
|
+
* `updated_at` stay. A file holding any of them is
|
|
5866
|
+
* rewritten without them in the folder's own form (two-space indent, a
|
|
5867
|
+
* trailing newline, the other keys in their order); one holding none, or
|
|
5868
|
+
* that is not a JSON object, travels byte for byte, and nothing outside the
|
|
5869
|
+
* element files is touched. `r.authorFieldsLeftOut` counts the files
|
|
5870
|
+
* rewritten. Pass `{ includeAuthorFields: true }` for a byte copy of your own
|
|
5871
|
+
* folder, as an archive of your own world.
|
|
5872
|
+
*
|
|
5843
5873
|
* 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
|
|
5874
|
+
* `includePrivateRecords`, `includeHidden` or `includeAuthorFields` that is
|
|
5875
|
+
* not a boolean, a `report` that is not a function, and (unless private
|
|
5876
|
+
* records are asked for) a `RECORDS.json` that is not a JSON array of objects or that
|
|
5847
5877
|
* marks an entry private without a producer name. Refuses (`OwWorldFileError`)
|
|
5848
5878
|
* an unsafe path or `topDir`, a duplicate path, a name some disk cannot hold,
|
|
5849
5879
|
* 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
|
|
|
@@ -5260,6 +5288,7 @@ function openersFor(tools, kind, address, surface) {
|
|
|
5260
5288
|
}
|
|
5261
5289
|
refuseUnknownOptions("openersFor", address, ADDRESS_KEYS);
|
|
5262
5290
|
const a = address;
|
|
5291
|
+
elementAddress({ ...a, form: a.form ?? "human" });
|
|
5263
5292
|
const page = elementAddress({ form: "human", world: a.world, type: a.type, id: a.id });
|
|
5264
5293
|
const world = a.world.toLowerCase();
|
|
5265
5294
|
const hasElement = a.type !== void 0 && a.type !== null;
|