@weiliang0121/capix-view 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei.liang (https://github.com/weiliang0121)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @weiliang0121/capix-view
 
-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.
+Versioned views over independently owned content for CAPiX.
+
+ES modules and TypeScript declarations. Requires Node.js 22.23.2 or newer.
+
+```sh
+npm install @weiliang0121/capix-view
+```
+
+## Public entry points
+
+- `@weiliang0121/capix-view`
+
+This package is part of CAPiX. The npm distribution contains compiled JavaScript, type declarations, and this package's MIT license. Reference services and client applications are not included in this package or the initial npm release.
+
+## License
+
+MIT. Copyright (c) 2026 wei.liang. See [LICENSE](./LICENSE).

package/dist/access.d.ts

@@ -0,0 +1,21 @@
+import type { ResourceEndpointActivity } from '@weiliang0121/capix-resources';
+import type { SourceBindings, SyncSourceBindings, ViewSources } from './source.js';
+import type { ViewIndex, ViewPersistence, ViewReference, ViewSelection, ViewSnapshot, ViewState } from './types.js';
+import type { View } from './view.js';
+export interface ViewAccess<Sources extends ViewSources> {
+    has(reference: ViewReference<Sources>): boolean;
+    members(): readonly ViewReference<Sources>[];
+    index(): Promise<ViewIndex<Sources>>;
+    capture(index?: ViewIndex<Sources>): Promise<ViewSnapshot<Sources>>;
+}
+export interface ViewManager<Sources extends ViewSources> {
+    has(reference: ViewReference<Sources>): boolean;
+    members(): readonly ViewReference<Sources>[];
+    include(references: readonly ViewReference<Sources>[]): ViewState<Sources>;
+    exclude(references: readonly ViewReference<Sources>[]): ViewState<Sources>;
+    index(): ViewIndex<Sources>;
+    capture(index?: ViewIndex<Sources>): ViewSnapshot<Sources>;
+    apply(selection: ViewSelection<Sources>): ViewState<Sources>;
+}
+export declare function openView<Sources extends ViewSources>(view: View<Sources>, sources: SourceBindings<Sources>, activity: ResourceEndpointActivity): ViewAccess<Sources>;
+export declare function openViewManager<Sources extends ViewSources>(view: View<Sources>, sources: SyncSourceBindings<Sources>, activity: ResourceEndpointActivity, persistence?: ViewPersistence<Sources>): ViewManager<Sources>;

package/dist/access.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{sourcePorts}from"./reading.js";function openView(view,sources,activity){activity.validate();const ports=sourcePorts(sources,Object.keys(view.exportState().sources),()=>activity.validate());return Object.freeze({has:__name(reference=>activity.runSync("has",{},()=>view.has(reference)),"has"),members:__name(()=>activity.runSync("members",{output:__name(members=>({count:members.length}),"output")},()=>view.members()),"members"),index:__name(()=>activity.runAsync("index",{output:__name(index=>({revision:index.basis.viewRevision,members:index.members.length}),"output")},()=>view.index(ports)),"index"),capture:__name(index=>activity.runAsync("capture",{output:__name(snapshot=>({revision:snapshot.basis.viewRevision,members:snapshot.entries.length}),"output")},()=>view.capture(ports,index)),"capture")})}__name(openView,"openView");function openViewManager(view,sources,activity,persistence){activity.validate();const ports=sourcePorts(sources,Object.keys(view.exportState().sources),()=>activity.validate()),writer=persistence?Object.freeze({commit:persistence.commit.bind(persistence)}):void 0;return Object.freeze({has:__name(reference=>activity.runSync("has",{},()=>view.has(reference)),"has"),members:__name(()=>activity.runSync("members",{output:__name(members=>({count:members.length}),"output")},()=>view.members()),"members"),include:__name(references=>activity.runSync("include",{output:__name(state=>({revision:state.revision,members:state.members.length}),"output")},()=>view.includeSync(ports,references,writer)),"include"),exclude:__name(references=>activity.runSync("exclude",{output:__name(state=>({revision:state.revision,members:state.members.length}),"output")},()=>view.excludeSync(references,writer)),"exclude"),index:__name(()=>activity.runSync("index",{output:__name(index=>({revision:index.basis.viewRevision,members:index.members.length}),"output")},()=>view.indexSync(ports)),"index"),capture:__name(index=>activity.runSync("capture",{output:__name(snapshot=>({revision:snapshot.basis.viewRevision,members:snapshot.entries.length}),"output")},()=>view.captureSync(ports,index)),"capture"),apply:__name(selection=>activity.runSync("apply",{output:__name(state=>({revision:state.revision,members:state.members.length}),"output")},()=>view.applySync(ports,selection,writer)),"apply")})}__name(openViewManager,"openViewManager");export{openView,openViewManager};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { View } from './view.js';
+export { openView, openViewManager, type ViewAccess, type ViewManager } from './access.js';
+export type { Awaitable, ViewKey, SourceIdentity, SourceStamp, SourceIndex, SourceInspection, SourceSnapshot, ViewSource, SyncViewSource, ViewSources, SyncViewSources, SourceBindings, SyncSourceBindings, SourceKey, SourceSummary, SourceValue } from './source.js';
+export type { ViewReference, ViewIndexEntry, ViewEntry, ViewState, ViewBasis, ViewIndex, ViewSnapshot, ViewSelection, ViewCommit, ViewSourceChecks, ViewPersistence } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+import{View}from"./view.js";import{openView,openViewManager}from"./access.js";export{View,openView,openViewManager};

package/dist/membership.d.ts

@@ -0,0 +1,7 @@
+import type { ViewSources } from './source.js';
+import type { ViewBasis, ViewReference, ViewState } from './types.js';
+export declare function members<Sources extends ViewSources>(value: readonly ViewReference<Sources>[], slots: readonly string[], deduplicate?: boolean): readonly ViewReference<Sources>[];
+export declare function memberIndex<Sources extends ViewSources>(members: readonly ViewReference<Sources>[]): ReadonlyMap<string, ReadonlySet<string | number>>;
+export declare function state<Sources extends ViewSources>(value: ViewState<Sources>): ViewState<Sources>;
+export declare function basis<Sources extends ViewSources>(value: ViewBasis<Sources>, current: ViewState<Sources>): ViewBasis<Sources>;
+export declare function sameMembers<Sources extends ViewSources>(left: readonly ViewReference<Sources>[], right: readonly ViewReference<Sources>[]): boolean;

package/dist/membership.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{checkIdentity,checkKey,checkStamp,conflict,data,exactKeys,object,sameIdentity}from"./value.js";function members(value,slots,deduplicate=!1){if(!Array.isArray(value))throw new TypeError("View members must be an array");const seen=new Map(slots.map(slot=>[slot,new Set])),accepted=data(value),unique=accepted.filter(member=>{if(object(member),exactKeys(member,["source","key"]),typeof member.source!="string")throw new TypeError("View member source must be named");const keys=seen.get(member.source);if(!keys)throw new TypeError("View member refers to an unknown source");if(checkKey(member.key),keys.has(member.key)){if(deduplicate)return!1;throw new TypeError("View members must be unique")}return keys.add(member.key),!0});return deduplicate?Object.freeze(unique):accepted}__name(members,"members");function memberIndex(members2){const index=new Map;for(const member of members2){let keys=index.get(member.source);keys||(keys=new Set,index.set(member.source,keys)),keys.add(member.key)}return index}__name(memberIndex,"memberIndex");function state(value){const accepted=data(value);if(object(accepted),exactKeys(accepted,["revision","sources","members"]),!Number.isSafeInteger(accepted.revision)||accepted.revision<0)throw new TypeError("Invalid view revision");object(accepted.sources);const slots=Object.keys(accepted.sources);for(const slot of slots){if(!slot.length)throw new TypeError("View source slots must be named");checkIdentity(accepted.sources[slot]),exactKeys(accepted.sources[slot],["id","scope"])}return Object.freeze({revision:accepted.revision,sources:accepted.sources,members:members(accepted.members,slots)})}__name(state,"state");function basis(value,current){const accepted=data(value);object(accepted),exactKeys(accepted,["viewRevision","sources"]),accepted.viewRevision!==current.revision&&conflict("View membership has changed"),object(accepted.sources),exactKeys(accepted.sources,Object.keys(current.sources));for(const slot of Object.keys(current.sources)){const stamp=accepted.sources[slot];checkStamp(stamp),sameIdentity(stamp,current.sources[slot])||conflict("View source identity or scope has changed")}return accepted}__name(basis,"basis");function sameMembers(left,right){return left.length===right.length&&left.every((entry,index)=>entry.source===right[index].source&&entry.key===right[index].key)}__name(sameMembers,"sameMembers");export{basis,memberIndex,members,sameMembers,state};

package/dist/reading.d.ts

@@ -0,0 +1,24 @@
+import type { SourceBindings, SyncSourceBindings, ViewSources } from './source.js';
+import type { ViewBasis, ViewIndex, ViewReference, ViewSnapshot, ViewState, ViewSourceChecks } from './types.js';
+export declare function sourcePorts<Sources extends ViewSources>(sources: SyncSourceBindings<Sources>, slots: readonly string[], validate?: () => void): SyncSourceBindings<Sources>;
+export declare function sourcePorts<Sources extends ViewSources>(sources: SourceBindings<Sources>, slots: readonly string[], validate?: () => void): SourceBindings<Sources>;
+export declare class ViewReading<Sources extends ViewSources> {
+    #private;
+    private readonly state;
+    constructor(state: ViewState<Sources>, sources: SourceBindings<Sources>);
+    index(): Promise<ViewIndex<Sources>>;
+    indexSync(): ViewIndex<Sources>;
+    selectionSync(members: readonly ViewReference<Sources>[], expected?: ViewBasis<Sources>): ViewIndex<Sources>;
+    additionsSync(members: readonly ViewReference<Sources>[]): ViewSourceChecks<Sources>;
+    capture(basis: ViewBasis<Sources>): Promise<ViewSnapshot<Sources>>;
+    captureSync(basis: ViewBasis<Sources>): ViewSnapshot<Sources>;
+    private check;
+    private checkSync;
+    private checked;
+    private directory;
+    private snapshot;
+    private entries;
+    private project;
+    private keys;
+    private values;
+}

package/dist/reading.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{checkKey,checkStamp,conflict,data,exactKeys,object,sameIdentity,sameStamp,synchronous}from"./value.js";function sourcePorts(sources,slots,validate){object(sources),exactKeys(sources,slots);const entries=slots.map(slot=>{const source=sources[slot];if(!source||typeof source.index!="function"||typeof source.inspect!="function"||typeof source.read!="function"||typeof source.check!="function")throw new TypeError("Invalid view source endpoint");const index=source.index.bind(source),inspect=source.inspect.bind(source),read=source.read.bind(source),check=source.check.bind(source),returned=__name(result=>{try{validate?.()}catch(error){throw Promise.resolve(result).catch(()=>{}),error}return result},"returned");return[slot,Object.freeze({index:__name(()=>(validate?.(),returned(index())),"index"),inspect:__name(keys=>(validate?.(),returned(inspect(keys))),"inspect"),read:__name((keys,stamp)=>(validate?.(),returned(read(keys,stamp))),"read"),check:__name(stamp=>(validate?.(),returned(check(stamp))),"check")})]});return Object.freeze(Object.fromEntries(entries))}__name(sourcePorts,"sourcePorts");class ViewReading{static{__name(this,"ViewReading")}state;#ports;#slots;constructor(state,sources){this.state=state,this.#slots=Object.keys(state.sources),this.#ports=sourcePorts(sources,this.#slots)}async index(){const directories=new Map;for(const slot of this.#slots){const keys=this.keys(slot);directories.set(slot,this.directory(slot,await this.#ports[slot].inspect(keys),keys))}const index=this.project(directories,this.state.members);return await this.check(index.basis),index}indexSync(){return this.selectionSync(this.state.members)}selectionSync(members,expected){const directories=new Map;for(const slot of this.#slots){const keys=this.keys(slot,members);directories.set(slot,this.directory(slot,synchronous(this.#ports[slot].inspect(keys),"Source inspection"),keys))}const index=this.project(directories,members);if(expected)for(const slot of this.#slots)sameStamp(index.basis.sources[slot],expected.sources[slot])||conflict("View source version has changed");return this.checkSync(index.basis),index}additionsSync(members){const stamps={};for(const slot of new Set(members.map(member=>member.source))){const keys=this.keys(slot,members),inspected=this.directory(slot,synchronous(this.#ports[slot].inspect(keys),"Source inspection"),keys);Object.defineProperty(stamps,slot,{value:inspected.stamp,enumerable:!0})}for(const[slot,stamp]of Object.entries(stamps))this.checked(synchronous(this.#ports[slot].check(stamp),"Source checking"));return Object.freeze(stamps)}async capture(basis){await this.check(basis);const snapshots=new Map;for(const slot of this.#slots){const keys=this.keys(slot);keys.length&&snapshots.set(slot,this.snapshot(slot,await this.#ports[slot].read(keys,basis.sources[slot]),basis,keys))}return await this.check(basis),this.values(basis,snapshots)}captureSync(basis){this.checkSync(basis);const snapshots=new Map;for(const slot of this.#slots){const keys=this.keys(slot);keys.length&&snapshots.set(slot,this.snapshot(slot,synchronous(this.#ports[slot].read(keys,basis.sources[slot]),"Source reading"),basis,keys))}return this.checkSync(basis),this.values(basis,snapshots)}async check(basis){for(const slot of this.#slots)this.checked(await this.#ports[slot].check(basis.sources[slot]))}checkSync(basis){for(const slot of this.#slots)this.checked(synchronous(this.#ports[slot].check(basis.sources[slot]),"Source checking"))}checked(result){if(typeof result!="boolean")throw new TypeError("Source checking must return a boolean");result||conflict("View source version has changed")}directory(slot,value,keys){const accepted=data(value);object(accepted),exactKeys(accepted,["stamp","entries"]),checkStamp(accepted.stamp),sameIdentity(accepted.stamp,this.state.sources[slot])||conflict("View source identity or scope has changed");const returned=this.entries(accepted.entries);if(returned.size!==keys.length||keys.some(key=>!returned.has(key)))throw new RangeError("Source must inspect every requested member and no others");for(const entry of accepted.entries)exactKeys(entry,["key","summary"]);return accepted}snapshot(slot,value,basis,keys){const accepted=data(value);object(accepted),exactKeys(accepted,["stamp","entries"]),checkStamp(accepted.stamp),sameStamp(accepted.stamp,basis.sources[slot])||conflict("Source returned content from another version");const returned=this.entries(accepted.entries);if(returned.size!==keys.length||keys.some(key=>!returned.has(key)))throw new RangeError("Source must return every requested member and no others");for(const entry of accepted.entries)exactKeys(entry,["key","value"]);return accepted}entries(entries){if(!Array.isArray(entries))throw new TypeError("Source entries must be an array");const keys=new Set;for(const entry of entries){if(object(entry),checkKey(entry.key),keys.has(entry.key))throw new TypeError("Source entries must be unique");keys.add(entry.key)}return keys}project(directories,members){const summaries=new Map(Array.from(directories,([slot,directory])=>[slot,new Map(directory.entries.map(entry=>[entry.key,entry.summary]))])),entries=members.map(member=>{const values=summaries.get(member.source);if(!values.has(member.key))throw new RangeError("View member is missing or outside the source scope");return Object.freeze({...member,summary:values.get(member.key)})}),stamps=Object.freeze(Object.fromEntries(Array.from(directories,([slot,directory])=>[slot,directory.stamp])));return Object.freeze({basis:Object.freeze({viewRevision:this.state.revision,sources:stamps}),members,entries:Object.freeze(entries)})}keys(slot,members=this.state.members){return Object.freeze(members.filter(member=>member.source===slot).map(member=>member.key))}values(basis,snapshots){const values=new Map(Array.from(snapshots,([slot,snapshot])=>[slot,new Map(snapshot.entries.map(entry=>[entry.key,entry.value]))])),entries=this.state.members.map(member=>Object.freeze({...member,value:values.get(member.source).get(member.key)}));return Object.freeze({basis,entries:Object.freeze(entries)})}}export{ViewReading,sourcePorts};

package/dist/source.d.ts

@@ -0,0 +1,53 @@
+export interface SourceIdentity {
+    readonly id: string;
+    readonly scope: string;
+}
+export interface SourceStamp extends SourceIdentity {
+    readonly version: string;
+}
+export type ViewKey = string | number;
+export type Awaitable<Value> = Value | PromiseLike<Value>;
+export interface SourceIndex<Key extends ViewKey, Summary> {
+    readonly stamp: SourceStamp;
+    readonly entries: readonly {
+        readonly key: Key;
+        readonly summary: Summary;
+    }[];
+}
+export interface SourceInspection<Key extends ViewKey, Summary> {
+    readonly stamp: SourceStamp;
+    readonly entries: readonly {
+        readonly key: Key;
+        readonly summary: Summary;
+    }[];
+}
+export interface SourceSnapshot<Key extends ViewKey, Value> {
+    readonly stamp: SourceStamp;
+    readonly entries: readonly {
+        readonly key: Key;
+        readonly value: Value;
+    }[];
+}
+export interface ViewSource<Key extends ViewKey, Summary, Value> {
+    index(): Awaitable<SourceIndex<Key, Summary>>;
+    inspect(keys: readonly Key[]): Awaitable<SourceInspection<Key, Summary>>;
+    read(keys: readonly Key[], expected: SourceStamp): Awaitable<SourceSnapshot<Key, Value>>;
+    check(expected: SourceStamp): Awaitable<boolean>;
+}
+export interface SyncViewSource<Key extends ViewKey, Summary, Value> extends ViewSource<Key, Summary, Value> {
+    index(): SourceIndex<Key, Summary>;
+    inspect(keys: readonly Key[]): SourceInspection<Key, Summary>;
+    read(keys: readonly Key[], expected: SourceStamp): SourceSnapshot<Key, Value>;
+    check(expected: SourceStamp): boolean;
+}
+export type ViewSources = Readonly<Record<string, ViewSource<any, any, any>>>;
+export type SyncViewSources = Readonly<Record<string, SyncViewSource<any, any, any>>>;
+export type SourceKey<Source> = Source extends ViewSource<infer Key, any, any> ? Key : never;
+export type SourceSummary<Source> = Source extends ViewSource<any, infer Summary, any> ? Summary : never;
+export type SourceValue<Source> = Source extends ViewSource<any, any, infer Value> ? Value : never;
+export type SourceBindings<Sources extends ViewSources> = {
+    readonly [Name in keyof Sources]: ViewSource<SourceKey<Sources[Name]>, SourceSummary<Sources[Name]>, SourceValue<Sources[Name]>>;
+};
+export type SyncSourceBindings<Sources extends ViewSources> = {
+    readonly [Name in keyof Sources]: SyncViewSource<SourceKey<Sources[Name]>, SourceSummary<Sources[Name]>, SourceValue<Sources[Name]>>;
+};

package/dist/source.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+import type { SourceIdentity, SourceKey, SourceStamp, SourceSummary, SourceValue, ViewSources } from './source.js';
+export type ViewReference<Sources extends ViewSources> = {
+    [Name in keyof Sources & string]: {
+        readonly source: Name;
+        readonly key: SourceKey<Sources[Name]>;
+    };
+}[keyof Sources & string];
+export type ViewIndexEntry<Sources extends ViewSources> = {
+    [Name in keyof Sources & string]: {
+        readonly source: Name;
+        readonly key: SourceKey<Sources[Name]>;
+        readonly summary: SourceSummary<Sources[Name]>;
+    };
+}[keyof Sources & string];
+export type ViewEntry<Sources extends ViewSources> = {
+    [Name in keyof Sources & string]: {
+        readonly source: Name;
+        readonly key: SourceKey<Sources[Name]>;
+        readonly value: SourceValue<Sources[Name]>;
+    };
+}[keyof Sources & string];
+export interface ViewState<Sources extends ViewSources> {
+    readonly revision: number;
+    readonly sources: {
+        readonly [Name in keyof Sources]: SourceIdentity;
+    };
+    readonly members: readonly ViewReference<Sources>[];
+}
+export interface ViewBasis<Sources extends ViewSources> {
+    readonly viewRevision: number;
+    readonly sources: {
+        readonly [Name in keyof Sources]: SourceStamp;
+    };
+}
+export interface ViewIndex<Sources extends ViewSources> {
+    readonly basis: ViewBasis<Sources>;
+    readonly members: readonly ViewReference<Sources>[];
+    readonly entries: readonly ViewIndexEntry<Sources>[];
+}
+export interface ViewSnapshot<Sources extends ViewSources> {
+    readonly basis: ViewBasis<Sources>;
+    readonly entries: readonly ViewEntry<Sources>[];
+}
+export interface ViewSelection<Sources extends ViewSources> {
+    readonly basis: ViewBasis<Sources>;
+    readonly members: readonly ViewReference<Sources>[];
+}
+export interface ViewCommit<Sources extends ViewSources> {
+    readonly checkedSources: ViewSourceChecks<Sources>;
+    readonly previous: ViewState<Sources>;
+    readonly state: ViewState<Sources>;
+}
+export type ViewSourceChecks<Sources extends ViewSources> = {
+    readonly [Name in keyof Sources]?: SourceStamp;
+};
+export interface ViewPersistence<Sources extends ViewSources> {
+    commit(change: ViewCommit<Sources>): undefined;
+}

package/dist/types.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/value.d.ts

@@ -0,0 +1,11 @@
+import type { SourceIdentity, SourceStamp, ViewKey } from './source.js';
+export declare function conflict(message: string): never;
+export declare function data<Value>(value: Value): Value;
+export declare function object(value: unknown): asserts value is Record<string, unknown>;
+export declare function exactKeys(value: object, keys: readonly string[]): void;
+export declare function checkIdentity(value: unknown): asserts value is SourceIdentity;
+export declare function checkStamp(value: unknown): asserts value is SourceStamp;
+export declare function sameIdentity(left: SourceIdentity, right: SourceIdentity): boolean;
+export declare function sameStamp(left: SourceStamp, right: SourceStamp): boolean;
+export declare function checkKey(key: unknown): asserts key is ViewKey;
+export declare function synchronous<Value>(value: Value, label: string): Exclude<Value, PromiseLike<unknown>>;

package/dist/value.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{types}from"node:util";import{RuntimeError}from"@weiliang0121/capix-contracts";function conflict(message){throw new RuntimeError("VIEW_CONFLICT",message)}__name(conflict,"conflict");function data(value){const visiting=new Set,copy=__name(input=>{if(input==null||typeof input=="string"||typeof input=="boolean"||typeof input=="number"&&Number.isFinite(input))return input;if(typeof input!="object"||types.isProxy(input))throw new TypeError("View content must be passive data");if(visiting.has(input))throw new TypeError("View content cannot contain cycles");const array=Array.isArray(input);if(!array&&Object.getPrototypeOf(input)!==Object.prototype&&Object.getPrototypeOf(input)!==null)throw new TypeError("View content cannot contain live objects");visiting.add(input);try{const result=array?[]:{};let reusable=Object.isFrozen(input);for(const key of Reflect.ownKeys(input)){if(array&&key==="length")continue;if(typeof key!="string")throw new TypeError("View content cannot contain symbol fields");const descriptor=Object.getOwnPropertyDescriptor(input,key);if(!("value"in descriptor)||!descriptor.enumerable)throw new TypeError("View content must use enumerable data fields");if(array&&(!/^(0|[1-9]\d*)$/.test(key)||Number(key)>=input.length))throw new TypeError("View arrays cannot contain named fields");const copied=copy(descriptor.value);copied!==descriptor.value&&(reusable=!1),Object.defineProperty(result,key,{value:copied,enumerable:!0,configurable:!0,writable:!0})}if(array&&Object.keys(input).length!==input.length)throw new TypeError("View arrays must be dense");return reusable?input:Object.freeze(result)}finally{visiting.delete(input)}},"copy");return copy(value)}__name(data,"data");function object(value){if(!value||typeof value!="object"||Array.isArray(value))throw new TypeError("Invalid view object")}__name(object,"object");function exactKeys(value,keys){if(Object.keys(value).length!==keys.length||keys.some(key=>!Object.hasOwn(value,key)))throw new TypeError("View fields do not match the contract")}__name(exactKeys,"exactKeys");function checkIdentity(value){if(object(value),typeof value.id!="string"||!/\S/.test(value.id)||typeof value.scope!="string"||!/\S/.test(value.scope))throw new TypeError("Invalid view source identity")}__name(checkIdentity,"checkIdentity");function checkStamp(value){if(checkIdentity(value),exactKeys(value,["id","scope","version"]),typeof value.version!="string"||!value.version.length)throw new TypeError("Invalid view source version")}__name(checkStamp,"checkStamp");function sameIdentity(left,right){return left.id===right.id&&left.scope===right.scope}__name(sameIdentity,"sameIdentity");function sameStamp(left,right){return sameIdentity(left,right)&&left.version===right.version}__name(sameStamp,"sameStamp");function checkKey(key){if(!(typeof key=="string"&&key.length>0)&&!(typeof key=="number"&&Number.isSafeInteger(key)&&key>=0))throw new TypeError("View keys must be nonempty strings or nonnegative safe integers")}__name(checkKey,"checkKey");function synchronous(value,label){if(value&&(typeof value=="object"||typeof value=="function")&&typeof value.then=="function")throw Promise.resolve(value).catch(()=>{}),new TypeError(`${label} must complete synchronously`);return value}__name(synchronous,"synchronous");export{checkIdentity,checkKey,checkStamp,conflict,data,exactKeys,object,sameIdentity,sameStamp,synchronous};

package/dist/view.d.ts

@@ -0,0 +1,20 @@
+import type { SourceBindings, SyncSourceBindings, ViewSources } from './source.js';
+import type { ViewIndex, ViewPersistence, ViewReference, ViewSelection, ViewSnapshot, ViewState } from './types.js';
+export declare class View<Sources extends ViewSources> {
+    #private;
+    constructor(state: ViewState<Sources>);
+    exportState(): ViewState<Sources>;
+    has(reference: ViewReference<Sources>): boolean;
+    members(): readonly ViewReference<Sources>[];
+    includeSync(sources: SyncSourceBindings<Sources>, references: readonly ViewReference<Sources>[], persistence?: ViewPersistence<Sources>): ViewState<Sources>;
+    excludeSync(references: readonly ViewReference<Sources>[], persistence?: ViewPersistence<Sources>): ViewState<Sources>;
+    index(sources: SourceBindings<Sources>): Promise<ViewIndex<Sources>>;
+    indexSync(sources: SyncSourceBindings<Sources>): ViewIndex<Sources>;
+    capture(sources: SourceBindings<Sources>, index?: ViewIndex<Sources>): Promise<ViewSnapshot<Sources>>;
+    captureSync(sources: SyncSourceBindings<Sources>, index?: ViewIndex<Sources>): ViewSnapshot<Sources>;
+    applySync(sources: SyncSourceBindings<Sources>, selection: ViewSelection<Sources>, persistence?: ViewPersistence<Sources>): ViewState<Sources>;
+    private beginMutation;
+    private install;
+    private current;
+    private indexBasis;
+}

package/dist/view.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{PersistenceError}from"@weiliang0121/capix-diagnostics";import{basis as acceptBasis,members as acceptMembers,memberIndex,sameMembers,state as acceptState}from"./membership.js";import{ViewReading}from"./reading.js";import{conflict,data,exactKeys,object,synchronous}from"./value.js";class View{static{__name(this,"View")}#state;#members;#mutating=!1;constructor(state){this.#state=acceptState(state),this.#members=memberIndex(this.#state.members)}exportState(){return this.#state}has(reference){const[member]=acceptMembers([reference],Object.keys(this.#state.sources));return this.#members.get(member.source)?.has(member.key)??!1}members(){return this.#state.members}includeSync(sources,references,persistence){this.beginMutation();try{const previous=this.#state,added=acceptMembers(references,Object.keys(previous.sources),!0).filter(member=>!this.#members.get(member.source)?.has(member.key));if(!added.length)return previous;const checkedSources=new ViewReading(previous,sources).additionsSync(added),members=Object.freeze([...previous.members,...added]);return this.install(previous,members,checkedSources,persistence)}finally{this.#mutating=!1}}excludeSync(references,persistence){this.beginMutation();try{const previous=this.#state,requested=acceptMembers(references,Object.keys(previous.sources),!0);if(!requested.some(member=>this.#members.get(member.source)?.has(member.key)))return previous;const removed=memberIndex(requested),members=Object.freeze(previous.members.filter(member=>!removed.get(member.source)?.has(member.key)));return this.install(previous,members,Object.freeze({}),persistence)}finally{this.#mutating=!1}}async index(sources){const state=this.#state,index=await new ViewReading(state,sources).index();return this.current(state),index}indexSync(sources){const state=this.#state,index=new ViewReading(state,sources).indexSync();return this.current(state),index}async capture(sources,index){const state=this.#state,reading=new ViewReading(state,sources),basis=index===void 0?(await reading.index()).basis:this.indexBasis(index,state);this.current(state);const snapshot=await reading.capture(basis);return this.current(state),snapshot}captureSync(sources,index){const state=this.#state,reading=new ViewReading(state,sources),basis=index===void 0?reading.indexSync().basis:this.indexBasis(index,state);this.current(state);const snapshot=reading.captureSync(basis);return this.current(state),snapshot}applySync(sources,selection,persistence){this.beginMutation();try{const previous=this.#state,accepted=data(selection);object(accepted),exactKeys(accepted,["basis","members"]);const basis=acceptBasis(accepted.basis,previous),members=acceptMembers(accepted.members,Object.keys(previous.sources));return new ViewReading(previous,sources).selectionSync(members,basis),this.install(previous,members,basis.sources,persistence)}finally{this.#mutating=!1}}beginMutation(){this.#mutating&&conflict("A view mutation is already in progress"),this.#mutating=!0}install(previous,members,checkedSources,persistence){if(this.current(previous),sameMembers(previous.members,members))return previous;if(!Number.isSafeInteger(previous.revision+1))throw new RangeError("View revision is exhausted");const state=Object.freeze({revision:previous.revision+1,sources:previous.sources,members}),lookup=memberIndex(members);if(persistence)try{if(synchronous(persistence.commit(Object.freeze({checkedSources,previous,state})),"View persistence")!==void 0)throw new TypeError("View persistence must return undefined")}catch(cause){throw cause instanceof PersistenceError?cause:new PersistenceError("view.commit",cause)}return this.#state=state,this.#members=lookup,state}current(state){this.#state!==state&&conflict("View membership changed during access")}indexBasis(value,state){const index=data(value);object(index),exactKeys(index,["basis","members","entries"]);const basis=acceptBasis(index.basis,state),members=acceptMembers(index.members,Object.keys(state.sources));if(sameMembers(members,state.members)||conflict("Directory members do not match the current view"),!Array.isArray(index.entries)||!sameMembers(index.entries,state.members))throw new TypeError("Directory entries do not match its members");for(const entry of index.entries)exactKeys(entry,["source","key","summary"]);return basis}}export{View};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@weiliang0121/capix-view",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@weiliang0121/capix-contracts": "0.1.0",
+    "@weiliang0121/capix-diagnostics": "0.1.0",
+    "@weiliang0121/capix-resources": "0.1.0"
+  },
+  "description": "Versioned views over independently owned content for CAPiX.",
+  "license": "MIT",
+  "author": "wei.liang (https://github.com/weiliang0121)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiliang0121/capix.git",
+    "directory": "server/view"
+  },
+  "engines": {
+    "node": ">=22.23.2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }