@cobol-ts/arrays 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @cobol-ts/arrays — ProjectedArray
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`ProjectedArray<T>` extends `ReadonlyArray<T>`. An ordinary `Array<T>` satisfies it.
+A lazy projected array preserves its native array interface without creating
+its child objects until they are accessed. Its `length` comes from the current
+logical record; its internal cached projections may retain more slots.
+
+`createProjectedArray(source)` wraps an empty native array using a proxy.
+Element lookup delegates to the supplied source, while `map`, `slice`,
+`forEach`, iteration, `at` and the other readonly array methods are inherited
+from `Array.prototype`. Operations such as `map` allocate their returned array
+just as they would for an ordinary JavaScript array. No data-format-specific
+logic or record ownership exists in this package. Mutation is rejected.
+
+The projection package supplies the mutable source and retains reusable
+child projections in pooled physical-record state. Borrowed elements are invalid
+after their owning file-result lease closes.
+
+## ArrayWithSize — reusable contiguous prefixes
+
+`ArrayWithSize<T>` is a small, independent abstraction for buffers where the
+valid data is exactly `values[0..size)`. Its backing array may retain entries
+beyond `size` after reset. `createArrayWithSize()`, `appendArrayWithSize()` and
+`resetArrayWithSize()` let a caller grow and reuse a prefix without allocating
+another array on each lease:
+
+```typescript
+const boundaries = createArrayWithSize<number>();
+appendArrayWithSize(boundaries, 100);
+appendArrayWithSize(boundaries, 124);
+resetArrayWithSize(boundaries); // size = 0, values' storage retained
+appendArrayWithSize(boundaries, 200); // overwrites the first slot
+```
+
+Reset invalidates the prefix; it does not clear object references beyond it.
+Do not use this abstraction *as the indexed lookup array* for sparse projected children. It **is** appropriate for the separate dense list of child references activated during the current lease. In the projection and ODO caches, sparse indexed storage remains independent of this `ArrayWithSize` cleanup prefix.
+
+## Projected-array access metrics
+
+`createProjectedArray(source, metrics?)` optionally counts direct Proxy `length` requests, numeric property selections and valid numeric selections. Its default `NullMetrics` performs no storage or I/O. A numeric index access calls the provider's length method to validate bounds; the projection package separately counts provider length-resolution work, selection, binding and cleanup. No new array elements are materialised by the counters.
+
+## Native arrays versus the Proxy adapter
+
+The `ProjectedArray` Proxy adapter is the **lazy** selection mechanism: numeric property access asks a source for its active length and selected element, and the projection layer manages reusable high-water child views. Small fixed-position COBOL arrays may instead use real JavaScript arrays of reusable projection children, selected by the COBOL projection runtime. That does not change the contract of `createProjectedArray` or make the Proxy unnecessary; symbolic/ODO and complex arrays still require it. The native-array strategy holds views, not scalar values, and the byte-backed borrowed lifetime is enforced by the owning projection/record binding rather than by JavaScript array indexing.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './src/arrays';
+export * from "./src/projected.array";
+export * from "./src/array.with.size";

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./src/arrays"), exports);
+__exportStar(require("./src/projected.array"), exports);
+__exportStar(require("./src/array.with.size"), exports);
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@cobol-ts/arrays",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "utilities about arrays",
+  "version": "0.0.1",
+  "main": "dist/index",
+  "types": "dist/index",
+  "browserslist": {
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ],
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ]
+  },
+  "dependencies": {
+    "@cobol-ts/metrics": "0.0.1"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.1.4",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^14.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.2.2"
+  },
+  "eslintConfig": {
+    "extends": [
+      "react-app",
+      "react-app/jest"
+    ],
+    "overrides": [
+      {
+        "files": [
+          "**/*.stories.*"
+        ],
+        "rules": {
+          "import/no-anonymous-default-export": "off"
+        }
+      }
+    ]
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/src/",
+    "build/"
+  ],
+  "keywords": [
+    "indexing"
+  ],
+  "license": "MIT",
+  "repository": "git@github.com:intellimaintain/intellimaintain.git",
+  "scripts": {
+    "test": "jest --config jest.config.json --env node",
+    "test:watch": "npm run test -- --watch",
+    "start": "react-scripts start"
+  }
 }