ac-storage 0.11.0 → 0.13.0

package/README.md

@@ -0,0 +1,32 @@
+# AC-Storage
+
+## Install
+
+```bash
+npm install ac-storage
+```
+
+## Example
+
+```ts
+import { ACStorage, StorageAccess } from 'ac-storage';
+
+const storage = new ACStorage('./store');
+storage.register({
+  'auth' : {
+    'default.json' : StorageAccess.JSON(),
+  },
+  'cache' : {
+    'last_access.txt' : StorageAccess.Text(),
+  }
+});
+
+const authAC = await storage.accessAsJSON('auth:default.json');
+authAC.setOne('id', 'user');
+
+const lastAccessAC = await storage.accessAsText('cache:last_access.txt');
+lastAccessAC.write('20250607');
+
+await storage.commit();
+```
+

package/dist/bundle.cjs

@@ -27,7 +27,7 @@ var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs$1);
 var fs__namespace$1 = /*#__PURE__*/_interopNamespaceDefault(fs$2);
 var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 
-let e$1 = class e extends Error{constructor(e){super(e),this.name="TreeNavigateError";}};const t$1="--tree-leaf";var i$1;let r$1 = class r{#e={};#t=".";#i=false;#r=true;constructor(){}static from(e,t={}){const r=new i$1;return r.#e=e,r.#t=t.delimiter??".",r.#i=t.allowWildcard??false,r.#r=t.allowRecursiveWildcard??true,r}subtree(t){const r=t.split(this.#t),a=this.#a(r,this.#e);if(!a)throw new e$1(`Path '${t}' does not exist`);if(i$1.#l(a.value)||i$1.#s(a.value))throw new e$1(`Path '${t}' is not a subtree`);const l=a.path.reduce(((e,t)=>e[t]),this.#e),s=new i$1;return s.#e=l,s.#t=this.#t,s.#i=this.#i,s}get(e,t){return this.walk(e,t)?.value??null}walk(e,t={}){if(""===e)return t.allowIntermediate?{value:this.#e,path:[]}:null;const r=e.split(this.#t),a=this.#a(r,this.#e);if(!a)return null;const l=a.value;return i$1.#l(l)?a:i$1.#s(l)?{value:l.value,path:a.path}:t.allowIntermediate?a:null}trace(e){const t=e.split(this.#t),r={treePath:[]},a=this.#a(t,this.#e,r);let l,s;if(a){const e=a.value;return i$1.#l(e)?(l=true,s=e):i$1.#s(e)?(l=true,s=e.value):(l=false,s=e),{find:true,isLeaf:l,value:s,nodePath:a?.path??[],tracePath:r.treePath,untracePath:t}}return {find:false,isLeaf:false,value:void 0,nodePath:[],tracePath:r.treePath,untracePath:t}}#a(e,t,r={treePath:[]}){const{treePath:a}=r,l=e.shift();if(null==l)return {value:t,path:[]};if("object"!=typeof t||i$1.#s(t))return e.unshift(l),null;if(a.push(l),l in t){const i=this.#a(e,t[l],r);if(i)return {value:i.value,path:[l,...i.path]}}else if(this.#i){if("*"in t){const i=this.#a(e,t["*"],r);if(i)return {value:i.value,path:["*",...i.path]}}if(this.#r&&"**/*"in t)return {value:t["**/*"],path:["**/*"]}}return null}static#l(e){return null==e||"object"!=typeof e}static#s(e){return 1==e[t$1]}};i$1=r$1;
+let e$1 = class e extends Error{constructor(e){super(e),this.name="TreeNavigateError";}};const t$1="--tree-leaf";var i$1;let r$1 = class r{#e={};#t=".";#i=false;#r=true;constructor(){}static from(e,t={}){const r=new i$1;return r.#e=e,r.#t=t.delimiter??".",r.#i=t.allowWildcard??false,r.#r=t.allowRecursiveWildcard??true,r}subtree(t){const r=t.split(this.#t),a=this.#a(r,this.#e);if(!a)throw new e$1(`Path '${t}' does not exist`);if(i$1.#l(a.value)||i$1.#s(a.value))throw new e$1(`Path '${t}' is not a subtree`);const l=a.path.reduce((e,t)=>e[t],this.#e),s=new i$1;return s.#e=l,s.#t=this.#t,s.#i=this.#i,s}get(e,t){return this.walk(e,t)?.value??null}walk(e,t={}){if(""===e)return t.allowIntermediate?{value:this.#e,path:[]}:null;const r=e.split(this.#t),a=this.#a(r,this.#e);if(!a)return null;const l=a.value;return i$1.#l(l)?a:i$1.#s(l)?{value:l.value,path:a.path}:t.allowIntermediate?a:null}trace(e){const t=e.split(this.#t),r={treePath:[]},a=this.#a(t,this.#e,r);let l,s;if(a){const e=a.value;return i$1.#l(e)?(l=true,s=e):i$1.#s(e)?(l=true,s=e.value):(l=false,s=e),{find:true,isLeaf:l,value:s,nodePath:a?.path??[],tracePath:r.treePath,untracePath:t}}return {find:false,isLeaf:false,value:void 0,nodePath:[],tracePath:r.treePath,untracePath:t}}#a(e,t,r={treePath:[]}){const{treePath:a}=r,l=e.shift();if(null==l)return {value:t,path:[]};if("object"!=typeof t||i$1.#s(t))return e.unshift(l),null;if(a.push(l),l in t){const i=this.#a(e,t[l],r);if(i)return {value:i.value,path:[l,...i.path]}}else if(this.#i){if("*"in t){const i=this.#a(e,t["*"],r);if(i)return {value:i.value,path:["*",...i.path]}}if(this.#r&&"**/*"in t)return {value:t["**/*"],path:["**/*"]}}return null}static#l(e){return null==e||"object"!=typeof e}static#s(e){return 1==e[t$1]}};i$1=r$1;
 
 class JSONAccessorError extends Error {
     constructor(message) {
@@ -35,6 +35,18 @@ class JSONAccessorError extends Error {
         this.name = 'AccessorError';
     }
 }
+class UnserializableTypeError extends JSONAccessorError {
+    constructor(key, value) {
+        super(`Unserializable data: '${value}' for field '${key}'`);
+        this.name = 'UnserializableTypeError';
+    }
+}
+class IncompatibleTypeError extends JSONAccessorError {
+    constructor(message) {
+        super(message);
+        this.name = 'IncompatibleTypeError';
+    }
+}
 
 const JSON_TYPE_FLAG = '--json-type';
 
@@ -188,10 +200,18 @@ function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function concatDotPath(prefix, key) {
-    return (prefix && prefix.length > 0) ? `${prefix}.${key}` : key;
+/**
+ * 경로 문자열을 연결하여 반환
+ */
+function dotJoin(prefix, key) {
+    return (prefix != null && prefix.length > 0) ? `${prefix}.${key}` : key;
 }
+/**
+ * 값이 json-accessor 호환 가능 타입인지 확인하고 타입명 반환, 호환 불가능할 경우 null 반환
+ */
 function getJSONTypeName(value) {
+    if (value == null)
+        return 'null';
     if (Array.isArray(value))
         return 'array';
     const typeName = typeof value;
@@ -216,10 +236,17 @@ class Flattener {
         this.typeChecker = typeChecker;
     }
     /**
-     * key-value 에 대한 경로 유효성 검사
+     * key-value 쌍에 대한 경로 유효성 검사후 `Array<[key, value]>` 형태로 반환
+     *
+     * @param key - dot(.)으로 구분된 경로 문자열
+     * @param value - 유효성 검사를 위한 값
+     * @return 인자를 [[key, value]] 형태로 반환
      */
     transform(key, value) {
+        // [[key, value]] 를 그대로 반환하는건 flat()과의 호환을 위함
+        // 추후 구현에서 한 key에서 여러 결과를 리턴하는 등의 확장 가능성이 있음
         if (key === '') {
+            // 루트 경로는 비허용
             throw new JSONAccessorError(`Invalid path: ${key}`);
         }
         if (this.navigate == null) {
@@ -230,7 +257,7 @@ class Flattener {
             if (traceResult.isLeaf) {
                 const node = traceResult.value;
                 this.typeChecker.check(key, value, node);
-                if (node.type === 'struct') {
+                if (value != null && node.type === 'struct') {
                     // struct 형식인 value에 대한 구조 검사
                     this.flatStruct({
                         target: value,
@@ -241,6 +268,8 @@ class Flattener {
                 return [[key, value]];
             }
             else {
+                // 경로는 존재하지만 노드의 중간인 경우
+                // value가 object 형태라면 flat()을 통해 유효성 검사를 진행
                 if (!isObject(value)) {
                     throw new JSONAccessorError(`Field '${key}' is not allowed`);
                 }
@@ -250,34 +279,41 @@ class Flattener {
                 });
             }
         }
+        // 경로상 존재하지 않는 경우
+        else if (traceResult.tracePath.length === 0) {
+            throw new JSONAccessorError(`Field '${key}' is not allowed`);
+        }
+        // 중간 경로까지는 존재하는 경우
         else {
-            // 경로상 존재하지 않는 경우
-            // 닿을 수 있는 마지막 노드의 타입이 struct, any 라면 허용됨
             const { tracePath } = traceResult;
             const reached = tracePath.join(DELIMITER);
             const node = this.navigate.get(reached);
+            // 닿을 수 있는 마지막 노드의 타입이 struct, any 라면 허용됨
             if (!node || (node.type !== 'struct' && node.type !== 'any')) {
                 throw new JSONAccessorError(`Field '${key}' is not allowed`);
             }
             return [[key, value]];
         }
     }
-    flat({ target, prefix, }) {
+    /**
+     * 객체를 평탄화하여 `Array<[key, value]>`로 반환
+     *
+     * 유효성 검증을 포함함
+     */
+    flat({ target, prefix }) {
         if (!this.navigate) {
             return this.flatWithoutNavigate({ target, prefix });
         }
         const navigate = this.navigate;
-        return Object.entries(target).flatMap(([key, value]) => {
-            const newKey = concatDotPath(prefix, key);
+        return Object.entries(target)
+            .flatMap(([key, value]) => {
+            const newKey = dotJoin(prefix, key);
             const node = navigate.get(newKey, { allowIntermediate: true });
             if (node == null) {
                 throw new JSONAccessorError(`Field '${newKey}' is not allowed`);
             }
             else if (isJSONTypeData(node)) {
                 this.typeChecker.check(newKey, value, node);
-                // @TODO : 배열 타입에 대한 세부 처리 필요
-                // 현재는 배열 경로까지만 flat이 이루어지므로
-                // get/set 시 배열 전체를 가져오거나 덮어쓰게됨
                 if (node.type === 'any') {
                     return this.flatWithoutNavigate({
                         target: value,
@@ -291,6 +327,12 @@ class Flattener {
                         structData: node,
                     });
                 }
+                else if (node.type === 'array') {
+                    // @TODO : 배열 타입에 대한 세부 처리 필요
+                    // 현재는 배열 경로까지만 flat이 이루어지므로
+                    // get/set 시 배열 전체를 가져오거나 덮어쓰게됨
+                    return [[newKey, value]];
+                }
                 else {
                     return [[newKey, value]];
                 }
@@ -302,7 +344,11 @@ class Flattener {
                 });
             }
             else {
-                throw new JSONAccessorError(`Logic error: ${newKey}`);
+                // 가져온 값이 JSONTypeData(탐색한 노드의 끝) 도 아니고
+                // 일반 object(중간 노드)도 아닌 다른 타입인 경우
+                //
+                // TreeNavigate<JSONTypeData> 에서 가져온 결과에선 나올 수 없으므로 데이터 오염이라고 판단
+                throw new JSONAccessorError(`Data corrupted: unexpected node type encountered. key: '${newKey}', value: ${value} (${typeof value})`);
             }
         });
     }
@@ -311,8 +357,9 @@ class Flattener {
      */
     flatStruct({ target, prefix, structData }) {
         // struct는 내부 구조에 대한 구조 검증이 없으므로 유효성 검증 없이 단순 평탄화
-        return Object.entries(target).flatMap(([key, value]) => {
-            const newKey = concatDotPath(prefix, key);
+        return Object.entries(target)
+            .flatMap(([key, value]) => {
+            const newKey = dotJoin(prefix, key);
             if (isObject(value)) {
                 return this.flatWithoutNavigate({
                     target: value,
@@ -325,11 +372,12 @@ class Flattener {
         });
     }
     /**
-     * 유효성 검증 없이 flatten 수행
+     * 유효성 검증 없이 평탄화 수행
      */
     flatWithoutNavigate({ target, prefix }) {
-        return Object.entries(target).flatMap(([key, value]) => {
-            const newKey = concatDotPath(prefix, key);
+        return Object.entries(target)
+            .flatMap(([key, value]) => {
+            const newKey = dotJoin(prefix, key);
             if (isObject(value)) {
                 return this.flatWithoutNavigate({
                     target: value,
@@ -350,20 +398,26 @@ class CompatibilityChecker {
         if (!this.isCompatible(value, typeData)) {
             const typeName = getJSONTypeName(value);
             if (typeName == null) {
-                throw new JSONAccessorError(`Invalid data type: ${typeName} in '${key}'`);
+                throw new UnserializableTypeError(key, value);
             }
             else if (typeName === 'null') {
-                throw new JSONAccessorError(`Field '${key}' is not nullable`);
+                throw new IncompatibleTypeError(`Incompatible type for field '${key}': expected '${typeData.type}' and not nullable, received null`);
             }
             else if (typeName === 'array' && typeData.type === 'array') {
-                throw new JSONAccessorError(`Field '${key}' array structure is incompatible`);
+                throw new IncompatibleTypeError(`Incompatible array structure for field '${key}'`);
+            }
+            else if (typeData.type === 'union') {
+                const expected = this.getUnionTypeNames(typeData);
+                throw new IncompatibleTypeError(`Incompatible type for field '${key}': expected one of (${expected.join(' | ')}), received ${value} ('${typeName}')`);
             }
             else {
-                throw new JSONAccessorError(`Field '${key}' must be a '${typeData.type}' but '${typeName}'`);
+                throw new IncompatibleTypeError(`Incompatible type for field '${key}': expected '${typeData.type}', received '${typeName}'`);
             }
         }
     }
     isCompatible(target, jsonTypeData) {
+        // jsonTypeData 타입이 primitive 인 경우
+        // union 타입 검사 시 isCompatible() 가 다시 호출된 경우 발생
         if (typeof jsonTypeData !== 'object') {
             return target === jsonTypeData;
         }
@@ -372,12 +426,12 @@ class CompatibilityChecker {
             if (targetType === null) {
                 return false;
             }
-            else if (targetType === 'null') {
-                return jsonTypeData.nullable;
-            }
             else if (jsonTypeData.type === 'any') {
                 return true;
             }
+            else if (targetType === 'null') {
+                return jsonTypeData.nullable;
+            }
             else if (jsonTypeData.type === 'union') {
                 for (const candidate of jsonTypeData.candidates) {
                     if (this.isCompatible(target, candidate)) {
@@ -402,9 +456,7 @@ class CompatibilityChecker {
         }
     }
     isArrayCompatible(array, arrayTypeData) {
-        if (!arrayTypeData.strict)
-            return true;
-        if (!arrayTypeData.element)
+        if (!arrayTypeData.strict || !arrayTypeData.element)
             return true;
         for (const ele of array) {
             if (!this.isCompatible(ele, arrayTypeData.element)) {
@@ -428,6 +480,16 @@ class CompatibilityChecker {
             return false;
         }
     }
+    getUnionTypeNames(union) {
+        return union.candidates.map((c) => {
+            if (typeof c === 'object') {
+                return c.type;
+            }
+            else {
+                return c.toString();
+            }
+        });
+    }
 }
 
 class SchemaFlattener {
@@ -498,6 +560,56 @@ class MockJSONFS {
     }
 }
 
+class DefaultValueProvider {
+    #navigate;
+    constructor(navigate = null) {
+        this.#navigate = navigate;
+    }
+    get(key) {
+        if (this.#navigate == null) {
+            return undefined;
+        }
+        const result = this.#navigate.walk(key, { allowIntermediate: true });
+        if (result == null) {
+            return undefined;
+        }
+        else if (isJSONTypeData(result.value)) {
+            const defaultValue = result.value.default_value;
+            return ((defaultValue != null)
+                ? defaultValue
+                : undefined);
+        }
+        else {
+            // for (const [key, value] of Object.entries(result.value)) {
+            //     console.log(key, value);
+            // }
+            return this.#getDefaultData(result.value);
+        }
+    }
+    #getDefaultData(typeData) {
+        if (t$1 in typeData) {
+            if (typeData.value.default_value != null) {
+                return typeData.value.default_value;
+            }
+            return undefined;
+        }
+        else {
+            let hasKey = false;
+            const result = {};
+            for (const [key, value] of Object.entries(typeData)) {
+                const defaultValue = this.#getDefaultData(value);
+                if (defaultValue !== undefined) {
+                    result[key] = defaultValue;
+                    hasKey = true;
+                }
+            }
+            return (hasKey
+                ? result
+                : undefined);
+        }
+    }
+}
+
 class JSONAccessor {
     static anyJSONType = JSONType.Any().nullable().value;
     filePath;
@@ -506,6 +618,7 @@ class JSONAccessor {
     jsonFS = new JSONFS();
     #tree = null;
     #flatter;
+    #defaultValueProvider;
     #isDropped = false;
     #changed = true;
     constructor(filePath, tree = null) {
@@ -515,9 +628,11 @@ class JSONAccessor {
             this.#tree = tree;
             this.explorer = r$1.from(tree, { delimiter: '.', allowWildcard: true, allowRecursiveWildcard: false });
             this.#flatter = new SchemaFlattener(this.explorer);
+            this.#defaultValueProvider = new DefaultValueProvider(this.explorer);
         }
         else {
             this.#flatter = new SchemaFlattener();
+            this.#defaultValueProvider = new DefaultValueProvider();
         }
     }
     get tree() {
@@ -569,13 +684,20 @@ class JSONAccessor {
     }
     getOne(key) {
         this.#ensureNotDropped();
-        return this.#getData(key);
+        let value = this.#getData(key);
+        if (value == null) {
+            value = this.#defaultValueProvider.get(key);
+        }
+        return value;
     }
     get(...keys) {
         this.#ensureNotDropped();
         const result = {};
         for (const key of keys) {
-            const value = this.#getData(key);
+            let value = this.#getData(key);
+            if (value == null) {
+                value = this.#defaultValueProvider.get(key);
+            }
             const resolved = resolveNestedRef(result, key, true);
             resolved.parent[resolved.key] = value;
         }