@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 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). Two names are one after OW-18's fold: NFC, then simple case
119
- folding, both Unicode 15.1's from its own files (`nfc` since 4.71.0, `simpleCaseFold`), never
120
- the runtime's `normalize`, whose Unicode is its ICU's (Node 22: 16.0).
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 `includeHidden` that is not a boolean, a
5845
- * `report` that is not a function, and (unless private records
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 { includePrivate: o.includePrivateRecords === true, includeHidden: o.includeHidden !== false, report: o.report };
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 isHiddenElement(f) {
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 false;
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 false;
3803
+ return null;
3798
3804
  }
3799
- if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return false;
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) data = withoutLink(data, parseWorld(data)).data;
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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.108.1",
3
+ "version": "4.109.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {