tungsten 0.4.13 → 0.5.0

package/dist/babelPlugins/BabelTransformDocInit.js

@@ -0,0 +1,201 @@
+// BabelTransformDocInit
+//
+// `DocInit(fn, serverValue)` - fn runs in the document head before <body>, so it has to be in the
+// html, not the bundle. This rewrites each call to `docInit(<id>, serverValue)` (a read of the
+// result, see src/docInit.ts) and collects fn into one generated script:
+//     window.__t_docInit = {};
+//     window.__t_docInitErrors = [];
+//     try { window.__t_docInit[<id>] = (fn)(); }
+//     catch (e) { window.__t_docInitErrors.push({ id: <id>, source: "<file>:<line>:<col> of fn", error: e }); throw e; }
+// which the server inlines into the head (readDocInitScript.ts / processHead.ts). The catch only
+// records: the throw stays uncaught in the head, so the console shows it where it happened and the
+// script stops there as any other would. The record is for the dev banner hydrate renders
+// (docInit.ts renderDocInitErrorBanner).
+//
+// DocInit is a global (types/index.d.ts), so a call is recognised by name: the callee must be the
+// identifier with no binding in scope. Ids are one counter for the process, so a re-transform of a
+// file under watch gives its calls fresh ids and the old ones go dead; the output file is rewritten
+// whole from the per-file map each time, so dead entries never run. An untransformed call reaches
+// the throwing global docInit.ts installs.
+import fs from 'fs';
+import { basename, dirname, relative, resolve } from 'path';
+import { createRequire } from 'module';
+import slash from '../slash.js';
+import { docInitErrorsWindowKey, docInitWindowKey } from '../settings.js';
+// The source-map reader, required on the first call that has a map: DocInit is rare, so most
+// compiles never need it. The map itself babel has already read (inputSourceMap, on by default).
+const require = createRequire(import.meta.url);
+let traceMapping;
+function loadTraceMapping() {
+  traceMapping ??= require('@jridgewell/trace-mapping'); // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion -- require() is untyped
+  return traceMapping;
+}
+const globalName = 'DocInit';
+const runtimeName = 'docInit';
+const runtimeModule = 'tungsten';
+function isGlobalDocInitCall(path) {
+  const callee = path.node.callee;
+  return callee.type === 'Identifier' && callee.name === globalName && !path.scope.hasBinding(globalName);
+}
+function hasGlobalDocInitCall(program) {
+  let found = false;
+  program.traverse({
+    CallExpression(callPath) {
+      if (!isGlobalDocInitCall(callPath)) return;
+      found = true;
+      callPath.stop();
+    }
+  });
+  return found;
+}
+// Has side effects: empties the output file, so a stale one from an earlier run is never served
+export function MakeBabelTransformDocInit(opts) {
+  const entriesByFile = new Map();
+  let nextId = 0;
+  fs.mkdirSync(dirname(opts.outputFile), {
+    recursive: true
+  });
+  fs.writeFileSync(opts.outputFile, '');
+  function writeOutputFile() {
+    const entries = [...entriesByFile.values()].flat().sort((a, b) => a.id - b.id);
+    fs.writeFileSync(opts.outputFile, entries.length === 0 ? '' : [`window.${docInitWindowKey} = {};`, `window.${docInitErrorsWindowKey} = [];`, ...entries.map(entry => entry.statement)].join('\n') + '\n');
+  }
+  return function BabelTransformDocInit(babel) {
+    const t = babel.types;
+    // per file; transforms are sync and sequential
+    let calls = [];
+    let runtimeLocal = null;
+    let tracer; // undefined: not looked for yet; null: the file has no map
+    // the fn can only run against the head's globals: anything it reaches from this module is gone
+    function checkSelfContained(fnPath) {
+      fnPath.traverse({
+        ReferencedIdentifier(idPath) {
+          if (!idPath.isIdentifier()) return;
+          const name = idPath.node.name;
+          const binding = idPath.scope.getBinding(name);
+          if (binding === undefined) return; // a real global: document, localStorage, ...
+          if (binding.path === fnPath || binding.path.isDescendant(fnPath)) return;
+          throw idPath.buildCodeFrameError(`${globalName}() function references '${name}' from outside the function. It runs in the` + ` document head, where nothing from this module exists - only globals like document and` + ` localStorage are available`);
+        },
+        ThisExpression(thisPath) {
+          const owner = thisPath.findParent(p => p.isFunction() && !p.isArrowFunctionExpression());
+          if (owner !== null && (owner === fnPath || owner.isDescendant(fnPath))) return;
+          throw thisPath.buildCodeFrameError(`'this' in a ${globalName}() function refers to the enclosing scope, which does not exist in` + ` the document head`);
+        }
+      });
+    }
+    function headStatement(id, fnNode, source) {
+      const windowKey = key => t.memberExpression(t.identifier('window'), t.identifier(key));
+      const assign = t.expressionStatement(t.assignmentExpression('=', t.memberExpression(windowKey(docInitWindowKey), t.numericLiteral(id), true), t.callExpression(t.cloneNode(fnNode, true), [])));
+      const record = t.expressionStatement(t.callExpression(t.memberExpression(windowKey(docInitErrorsWindowKey), t.identifier('push')), [t.objectExpression([t.objectProperty(t.identifier('id'), t.numericLiteral(id)), t.objectProperty(t.identifier('source'), t.stringLiteral(source)), t.objectProperty(t.identifier('error'), t.identifier('e'))])]));
+      const statement = t.tryStatement(t.blockStatement([assign]), t.catchClause(t.identifier('e'), t.blockStatement([record, t.throwStatement(t.identifier('e'))])));
+      const result = babel.transformFromAstSync(t.file(t.program([statement])), undefined, {
+        babelrc: false,
+        configFile: false,
+        ast: false,
+        code: true,
+        comments: false
+      });
+      if (result === null || typeof result.code !== 'string') {
+        throw new Error(`BabelTransformDocInit: could not generate the head entry for doc init ${id}`);
+      }
+      return result.code;
+    }
+    // where the file's source map says a position came from - the .tsx behind tsc's .jsx
+    function originalPosition(state, filename, line, column) {
+      const inputMap = state.file.inputMap;
+      if (inputMap === null) return undefined;
+      if (tracer === undefined) {
+        // babel hands over a convert-source-map object; the raw map is what the reader takes
+        const raw = 'toObject' in inputMap && typeof inputMap.toObject === 'function' ? inputMap.toObject() // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion -- untyped by babel
+        : inputMap;
+        tracer = new (loadTraceMapping().TraceMap)(raw); // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion -- as above
+      }
+      if (tracer === null) return undefined;
+      const position = loadTraceMapping().originalPositionFor(tracer, {
+        line,
+        column
+      });
+      if (position.source === null) return undefined;
+      // sources are relative to the map, which tsc writes beside the file
+      return {
+        file: resolve(dirname(filename), position.source),
+        line: position.line,
+        column: position.column
+      };
+    }
+    // file:line:column of the function itself, 1-based like an editor; the original source where a map says
+    function callSite(fnPath, state, filename) {
+      const displayPath = file => opts.projectDir === undefined ? basename(file) : slash(relative(opts.projectDir, file));
+      const start = fnPath.node.loc?.start;
+      if (start === undefined) return displayPath(filename);
+      const original = originalPosition(state, filename, start.line, start.column);
+      const {
+        file,
+        line,
+        column
+      } = original ?? {
+        file: filename,
+        line: start.line,
+        column: start.column
+      };
+      return `${displayPath(file)}:${line}:${column + 1}`;
+    }
+    function rewriteCall(callPath, local, state, filename) {
+      const args = callPath.get('arguments');
+      const fnPath = args[0];
+      if (fnPath === undefined || !(fnPath.isArrowFunctionExpression() || fnPath.isFunctionExpression())) {
+        throw callPath.buildCodeFrameError(`${globalName}() takes an inline function expression as its first argument - it is inlined` + ` into the document head at build, so it cannot be a reference`);
+      }
+      if (fnPath.node.async === true || fnPath.node.generator === true) {
+        throw fnPath.buildCodeFrameError(`a ${globalName}() function runs synchronously in the document head, so it cannot be async` + ` or a generator`);
+      }
+      if (fnPath.node.params.length > 0) {
+        throw fnPath.buildCodeFrameError(`a ${globalName}() function takes no parameters - nothing calls it with any`);
+      }
+      if (args.length > 2) {
+        throw callPath.buildCodeFrameError(`${globalName}() takes a function and an optional server value, nothing more`);
+      }
+      checkSelfContained(fnPath);
+      const id = nextId++;
+      const entry = {
+        id,
+        statement: headStatement(id, fnPath.node, callSite(fnPath, state, filename))
+      };
+      callPath.node.callee = t.identifier(local.name);
+      callPath.node.arguments = [t.numericLiteral(id), ...callPath.node.arguments.slice(1)];
+      return entry;
+    }
+    return {
+      name: 'BabelTransformDocInit',
+      visitor: {
+        Program: {
+          enter(path, state) {
+            calls = [];
+            runtimeLocal = null;
+            tracer = undefined;
+            // the substring gate keeps the pre-scan off the files that cannot need it
+            if (!state.file.code.includes(globalName)) return;
+            if (!hasGlobalDocInitCall(path)) return;
+            // inserted now, not at exit, so the other plugins see it as any other import
+            runtimeLocal = path.scope.generateUidIdentifier(runtimeName);
+            path.unshiftContainer('body', t.importDeclaration([t.importSpecifier(runtimeLocal, t.identifier(runtimeName))], t.stringLiteral(runtimeModule)));
+          },
+          // after the presets have run on the function bodies: types stripped, jsx compiled
+          exit(_path, state) {
+            const filename = state.filename ?? ''; // eslint-disable-line @typescript-eslint/no-unnecessary-condition -- tsc sees string | undefined here, eslint's type info does not
+            if (calls.length === 0 && !entriesByFile.has(filename)) return;
+            const local = runtimeLocal;
+            const entries = local === null ? [] : calls.map(callPath => rewriteCall(callPath, local, state, filename));
+            if (entries.length === 0) entriesByFile.delete(filename);else entriesByFile.set(filename, entries);
+            writeOutputFile();
+          }
+        },
+        CallExpression(path) {
+          if (runtimeLocal === null) return;
+          if (isGlobalDocInitCall(path)) calls.push(path);
+        }
+      }
+    };
+  };
+}

package/dist/babelPlugins/BabelTransformPackageImports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BabelTransformPackageImports.d.ts","sourceRoot":"","sources":["../../src/babelPlugins/BabelTransformPackageImports.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BabelTransformPackageImports.d.ts","sourceRoot":"","sources":["../../src/babelPlugins/BabelTransformPackageImports.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAMrD,OAAO,EAGH,QAAQ,EACX,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAsC5C,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAA;AAErE,MAAM,MAAM,QAAQ,GAAG;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,QAAQ,CAAA;IACd,WAAW,EAAE,WAAW,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAA;AAEnD,MAAM,MAAM,WAAW,GAAG;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,WAAW,CAAA;IACjB,iBAAiB,EAAE,MAAM,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;CACxB,CAAA;AAGD,MAAM,MAAM,WAAW,GAAG;IACtB,CAAC,GAAG,EAAC,MAAM,GAAG,WAAW,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IACvC,KAAK,EAAE,MAAM,EAAE,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,CAAC,GAAG,EAAC,MAAM,GAAG,cAAc,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAC9B,IAAI,EAAE,QAAQ,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,iCAAiC,GAAG,mBAAmB,GAAG;IAClE,cAAc,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,EAAE,CAAA;AAEnC,KAAK,IAAI,GAAG;IACR,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,iBAAiB,EAAE,MAAM,CAAA;IACzB,qBAAqB,EAAE,MAAM,CAAA;IAC7B,2BAA2B,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAChD,kBAAkB,EAAE,eAAe,CAAA;IACnC,eAAe,EAAE,eAAe,CAAA;IAChC,aAAa,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;IAGxC,QAAQ,EAAE,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,EAAE,CAAA;CAC/C,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;AAC3D,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,CAAA;AACjE,MAAM,MAAM,oCAAoC,GAC1C,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAA;AACpG,MAAM,MAAM,kCAAkC,GACxC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAmC,MAAM,CAAA;AAChF,MAAM,MAAM,uCAAuC,GAC7C,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAmC,MAAM,CAAA;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,KAAK,MAAM,CAAA;AACrF,MAAM,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,KAAK,MAAM,CAAA;AAuDzF,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,IAAI;;eAi8BpC,SAAS;;kCAkBmB,QAAQ,CAAC,iBAAiB,CAAC;;;EAmH7E"}

package/dist/babelPlugins/BabelTransformPackageImports.js

@@ -856,16 +856,7 @@ export function MakeBabelTransformPackageImports(opts) {
               const importTarget = tallied('resolve import target', () => resolveImportTarget(location, dirname(filename), require));
               // Should do some checking here to show helpful errors about bad imports
               if (importTarget === location) {
-                //console.log()
-                // errorOut(errorMessage(
-                //     'BabelTransformPackageImports',
-                //     `import '${location}' in '${filename}' appears to refer to a node package.`
-                //     + ` This file is being processed as client-side code.`
-                //     + ` Client-side code cannot import node packages.`
-                //     + `\nIf you need to exclude files from client side compilation,`
-                //     + ` use exclude: glob-pattern in the project's ${packageName} config.`
-                // ))
-                throwError('BabelTransformPackageImports', `import '${location}' in '${filename}' appears to refer to a node package.` + ` This file is being processed as client-side code.` + ` Client-side code cannot import node packages.` + `\nIf you need to exclude files from client side compilation,` + ` use exclude: glob-pattern in the project's ${packageName} config.`);
+                throwError('BabelTransformPackageImports', `import '${location}' in '${filename}' appears to refer to a node package.` + ` This file is being processed as client-side code.` + ` Client-side code cannot import node packages.` + `\nTo keep a file out of client side compilation, use ignorePatterns` + ` (or clientDirs / rawDirs) in the project's ${packageName} config.`);
                 return;
               }
               //console.log('** importTarget', importTarget)

package/dist/babelPlugins/transformPackageImports/getWebLocationOfPackageFile.js

@@ -15,7 +15,7 @@ function getPackageDirForDir(dir) {
 }
 function getPackageDirForFile(file) {
   const dir = getPackageDirForDir(dirname(file));
-  if (dir === undefined) throw new TungstenError(`MakeBabelTransformPackageImports Error: could not find package dir for file ${file}`);
+  if (dir === undefined) throw new TungstenError(`getPackageDirForFile Error: could not find package dir for file ${file}`);
   return dir;
 }
 // function getWebLocationOfPackageFile(file: string): string {

package/dist/bin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bin/index.ts"],"names":[],"mappings":"AAoHA,OAAO,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bin/index.ts"],"names":[],"mappings":"AA2HA,OAAO,EAAE,CAAA"}

package/dist/bin/index.js

@@ -1,5 +1,5 @@
 import { enableCompileCache, flushCompileCache } from 'node:module';
-import { cliOut, cliWarn } from '../cliOutput.js';
+import { cliFatal, cliOut, cliWarn } from '../cliOutput.js';
 import { beginStartupProfiling } from '../timeProfiler.js';
 // get command line args
 const args = process.argv.slice(2);
@@ -32,82 +32,89 @@ if (profileModulesArg !== undefined) {
   } = await import('./moduleLoadAnalysis.js');
   registerModuleLoadAnalysis(profileModulesArg.split('=')[1]);
 }
-switch (command) {
-  case undefined:
-  case '':
-  case 'help':
-  case '--help':
-  case '-h':
-    {
-      await import('./commands/help.js');
-      break;
-    }
-  case 'dev':
-    {
-      cliOut(`Starting Tungsten dev mode`);
-      beginStartupProfiling(profile);
-      // set env before loading the next file, to set the env before file imports
-      process.env.__TUNGSTEN_ENV = 'development';
-      await import('./commands/dev.js');
-      break;
-    }
-  case 'devmon':
-    {
-      cliOut(`Starting Tungsten auto-restart dev mode`);
-      process.env.__TUNGSTEN_ENV = 'development';
-      await import('./commands/devmon.js');
-      break;
-    }
-  case 'build':
-    {
-      if (args.includes('--help') || args.includes('-h')) {
-        await import('./commands/buildHelp.js');
+// a command module's top-level await rejecting is the command failing to start (an env schema
+// that fails, a missing file): report it as such, not as node's uncaught-exception dump
+try {
+  switch (command) {
+    case undefined:
+    case '':
+    case 'help':
+    case '--help':
+    case '-h':
+      {
+        await import('./commands/help.js');
         break;
       }
-      // announce before the import: resolving the build's dependencies is a long silent wait
-      if (!args.includes('--quiet')) cliOut(`Starting Tungsten production build`);
-      beginStartupProfiling(profile);
-      process.env.__TUNGSTEN_ENV = 'production';
-      process.env.__TUNGSTEN_DEBUG = 'true';
-      await import('./commands/build.js');
-      break;
-    }
-  case 'start':
-    {
-      cliOut(`Starting Tungsten server`);
-      process.env.__TUNGSTEN_ENV = 'production';
-      await import('./commands/start.js');
-      break;
-    }
-  case 'static':
-    {
-      cliOut(`Starting Tungsten static site preview`);
-      //process.env.__TUNGSTEN_ENV = 'production'
-      await import('./commands/static.js');
-      break;
-    }
-  case 'clean':
-    {
-      await import('./commands/clean.js');
-      break;
-    }
-  case 'compile':
-    {
-      beginStartupProfiling(profile);
-      process.env.__TUNGSTEN_ENV = 'development';
-      await import('./commands/compile.js');
-      break;
-    }
-  case 'compile-simple-package':
-    {
-      await import('./commands/compileSimplePackage.js');
-      break;
-    }
-  default:
-    {
-      cliWarn(`tungsten: unknown command "${command}" (run "tungsten --help" for usage)`);
-      process.exit(1);
-    }
+    case 'dev':
+      {
+        cliOut(`Starting Tungsten dev mode`);
+        beginStartupProfiling(profile);
+        // set env before loading the next file, to set the env before file imports
+        process.env.__TUNGSTEN_ENV = 'development';
+        await import('./commands/dev.js');
+        break;
+      }
+    case 'devmon':
+      {
+        cliOut(`Starting Tungsten auto-restart dev mode`);
+        process.env.__TUNGSTEN_ENV = 'development';
+        await import('./commands/devmon.js');
+        break;
+      }
+    case 'build':
+      {
+        if (args.includes('--help') || args.includes('-h')) {
+          await import('./commands/buildHelp.js');
+          break;
+        }
+        // announce before the import: resolving the build's dependencies is a long silent wait
+        if (!args.includes('--quiet')) cliOut(`Starting Tungsten production build`);
+        beginStartupProfiling(profile);
+        process.env.__TUNGSTEN_ENV = 'production';
+        process.env.__TUNGSTEN_DEBUG = 'true';
+        await import('./commands/build.js');
+        break;
+      }
+    case 'start':
+      {
+        cliOut(`Starting Tungsten server`);
+        process.env.__TUNGSTEN_ENV = 'production';
+        await import('./commands/start.js');
+        break;
+      }
+    case 'static':
+      {
+        cliOut(`Starting Tungsten static site preview`);
+        //process.env.__TUNGSTEN_ENV = 'production'
+        await import('./commands/static.js');
+        break;
+      }
+    case 'clean':
+      {
+        await import('./commands/clean.js');
+        break;
+      }
+    case 'compile':
+      {
+        beginStartupProfiling(profile);
+        process.env.__TUNGSTEN_ENV = 'development';
+        await import('./commands/compile.js');
+        break;
+      }
+    case 'compile-simple-package':
+      {
+        await import('./commands/compileSimplePackage.js');
+        break;
+      }
+    default:
+      {
+        cliWarn(`tungsten: unknown command "${command}" (run "tungsten --help" for usage)`);
+        process.exit(1);
+      }
+  }
+} catch (e) {
+  cliFatal(e);
+  process.exit(1);
 }
 // Node only writes the compile cache when the process exits, and dev/start are killed rather than
 // exited - signals skip exit handling - so they would populate the cache and then throw it away,

package/dist/browserStorage.d.ts

@@ -1,26 +1,64 @@
 import { AnyComponent } from './AnyComponent.js';
-export declare class TungstenLocalStorage<LocalStorage extends object> {
-    #private;
-    get: <K extends keyof LocalStorage & string>(key: K) => LocalStorage[K] | undefined;
-    set: <K extends keyof LocalStorage & string>(key: K, value: LocalStorage[K]) => void;
-    clear: () => void;
-    key: (index: number) => string | null;
-    get length(): number;
-    delete: <K extends keyof LocalStorage & string>(key: K) => void;
-    subscribe: <K extends keyof LocalStorage & string>(element: AnyComponent, key: K) => void;
-    sync: <K extends keyof LocalStorage & string>(element: AnyComponent, key: K) => LocalStorage[K] | undefined;
+type StorageKey<Schema> = keyof Schema & string;
+export interface Transformer<Allowed> {
+    stringify: (value: Allowed) => string;
+    parse: (text: string) => unknown;
 }
-export declare function makeLocalStorage<LocalStorage extends object>(): TungstenLocalStorage<LocalStorage>;
-export declare class TungstenSessionStorage<SessionStorage extends object> {
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const rawTransformer: Transformer<string>;
+export declare const jsonTransformer: Transformer<JsonValue>;
+type AllStrings<Schema> = {
+    [K in keyof Schema]: string;
+};
+type TransformerFor<Schema extends object> = Transformer<Schema[StorageKey<Schema>]>;
+type TransformerOption<Schema extends object> = Schema[StorageKey<Schema>] extends string ? {
+    transformer?: TransformerFor<Schema>;
+} : {
+    transformer: TransformerFor<Schema>;
+};
+export type BrowserStorageOptions<Schema extends object> = {
+    defaults?: Schema;
+    serverDefaults?: Schema;
+} & TransformerOption<Schema>;
+export declare class TungstenBrowserStorage<Schema extends object, Missing = undefined> {
     #private;
-    get: <K extends keyof SessionStorage & string>(key: K) => SessionStorage[K] | undefined;
-    set: <K extends keyof SessionStorage & string>(key: K, value: SessionStorage[K]) => void;
+    constructor({ storage, transformer, defaults, host }: {
+        storage: Storage;
+        transformer: TransformerFor<Schema>;
+        defaults?: Schema | undefined;
+        host?: Window | null;
+    });
+    [Symbol.dispose](): void;
+    get: <K extends StorageKey<Schema>>(key: K) => Schema[K] | Missing;
+    set: <K extends StorageKey<Schema>>(key: K, value: Schema[K]) => void;
     clear: () => void;
     key: (index: number) => string | null;
     get length(): number;
-    delete: <K extends keyof SessionStorage & string>(key: K) => void;
-    subscribe: <K extends keyof SessionStorage & string>(element: AnyComponent, key: K) => void;
-    sync: <K extends keyof SessionStorage & string>(element: AnyComponent, key: K) => SessionStorage[K] | undefined;
+    delete: <K extends StorageKey<Schema>>(key: K) => void;
+    subscribe: <K extends StorageKey<Schema>>(element: AnyComponent, key: K) => void;
+    unsubscribe: <K extends StorageKey<Schema>>(element: AnyComponent, key: K) => void;
+    unsubscribeAll: (element: AnyComponent) => void;
+    sync: <K extends StorageKey<Schema>>(element: AnyComponent, key: K) => Missing | Schema[K];
+}
+export declare class TungstenLocalStorage<LocalStorage extends object, Missing = undefined> extends TungstenBrowserStorage<LocalStorage, Missing> {
+    constructor(transformer: TransformerFor<LocalStorage>, defaults?: LocalStorage | undefined);
+}
+export declare class TungstenSessionStorage<SessionStorage extends object, Missing = undefined> extends TungstenBrowserStorage<SessionStorage, Missing> {
+    constructor(transformer: TransformerFor<SessionStorage>, defaults?: SessionStorage | undefined);
 }
-export declare function makeSessionStorage<SessionStorage extends object>(): TungstenSessionStorage<SessionStorage>;
+type WithDefaults<Schema extends object> = BrowserStorageOptions<Schema> & {
+    defaults: Schema;
+};
+type WithoutDefaults<Schema extends object> = BrowserStorageOptions<Schema> & {
+    defaults?: undefined;
+};
+export declare function makeLocalStorage<LocalStorage extends AllStrings<LocalStorage>>(): TungstenLocalStorage<LocalStorage>;
+export declare function makeLocalStorage<LocalStorage extends object>(options: WithDefaults<LocalStorage>): TungstenLocalStorage<LocalStorage, never>;
+export declare function makeLocalStorage<LocalStorage extends object>(options: WithoutDefaults<LocalStorage>): TungstenLocalStorage<LocalStorage>;
+export declare function makeSessionStorage<SessionStorage extends AllStrings<SessionStorage>>(): TungstenSessionStorage<SessionStorage>;
+export declare function makeSessionStorage<SessionStorage extends object>(options: WithDefaults<SessionStorage>): TungstenSessionStorage<SessionStorage, never>;
+export declare function makeSessionStorage<SessionStorage extends object>(options: WithoutDefaults<SessionStorage>): TungstenSessionStorage<SessionStorage>;
+export {};
 //# sourceMappingURL=browserStorage.d.ts.map

package/dist/browserStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browserStorage.d.ts","sourceRoot":"","sources":["../src/browserStorage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAgBhD,qBAAa,oBAAoB,CAAC,YAAY,SAAS,MAAM;;IAEzD,GAAG,GAAI,CAAC,SAAS,MAAM,YAAY,GAAG,MAAM,EAAE,KAAK,CAAC,KAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAIjF;IACD,GAAG,GAAI,CAAC,SAAS,MAAM,YAAY,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,YAAY,CAAC,CAAC,CAAC,UAG3E;IACD,KAAK,aAKJ;IACD,GAAG,GAAI,OAAO,MAAM,mBAA4B;IAChD,IAAI,MAAM,WAAiC;IAC3C,MAAM,GAAI,CAAC,SAAS,MAAM,YAAY,GAAG,MAAM,EAAE,KAAK,CAAC,UAGtD;IACD,SAAS,GAAI,CAAC,SAAS,MAAM,YAAY,GAAG,MAAM,EAAE,SAAS,YAAY,EAAE,KAAK,CAAC,UAGhF;IACD,IAAI,GAAI,CAAC,SAAS,MAAM,YAAY,GAAG,MAAM,EAAE,SAAS,YAAY,EAAE,KAAK,CAAC,iCAI3E;CAeJ;AACD,wBAAgB,gBAAgB,CAAC,YAAY,SAAS,MAAM,KAAK,oBAAoB,CAAC,YAAY,CAAC,CAGlG;AAGD,qBAAa,sBAAsB,CAAC,cAAc,SAAS,MAAM;;IAE7D,GAAG,GAAI,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,EAAE,KAAK,CAAC,KAAG,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,CAIrF;IACD,GAAG,GAAI,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,cAAc,CAAC,CAAC,CAAC,UAG/E;IACD,KAAK,aAKJ;IACD,GAAG,GAAI,OAAO,MAAM,mBAA8B;IAClD,IAAI,MAAM,WAAmC;IAC7C,MAAM,GAAI,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,EAAE,KAAK,CAAC,UAGxD;IACD,SAAS,GAAI,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,EAAE,SAAS,YAAY,EAAE,KAAK,CAAC,UAGlF;IACD,IAAI,GAAI,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,EAAE,SAAS,YAAY,EAAE,KAAK,CAAC,mCAI7E;CAeJ;AACD,wBAAgB,kBAAkB,CAAC,cAAc,SAAS,MAAM,KAAK,sBAAsB,CAAC,cAAc,CAAC,CAG1G"}
+{"version":3,"file":"browserStorage.d.ts","sourceRoot":"","sources":["../src/browserStorage.ts"],"names":[],"mappings":"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"}