{"id":19777440,"url":"https://github.com/ilib-js/ilib-loader","last_synced_at":"2025-04-30T19:32:24.153Z","repository":{"id":37609937,"uuid":"412344168","full_name":"iLib-js/ilib-loader","owner":"iLib-js","description":"Code to load data files","archived":true,"fork":false,"pushed_at":"2024-11-12T17:43:51.000Z","size":109,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-05T02:24:39.303Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iLib-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-10-01T05:46:32.000Z","updated_at":"2024-11-21T22:03:29.000Z","dependencies_parsed_at":"2023-12-11T08:15:42.321Z","dependency_job_id":null,"html_url":"https://github.com/iLib-js/ilib-loader","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iLib-js","download_url":"https://codeload.github.com/iLib-js/ilib-loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251769485,"owners_count":21640911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T05:24:53.900Z","updated_at":"2025-04-30T19:32:24.146Z","avatar_url":"https://github.com/iLib-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003e :warning: **Deprecation Notice** :warning:\n\u003e This repository has been deprecated. Please use the corresponding package from the [iLib-js monorepo](https://github.com/iLib-js/ilib-mono) instead.\n\n# ilib-loader\n\nThese are ilib classes that know how to load files in various platforms. The files can\nbe arbitrary files.\n\nUsage\n-----\n\nFirst, create a loader instance using the LoaderFactory function. This loader\nis a singleton so you only get one loader per run of your app. The type of the\nloader that is created from the loader factory is dependent on the platform\nas returned by the `getPlatform()` function in the `ilib-env` package.\n\nTo create a new loader from the factory:\n\n```\nimport LoaderFactory from 'ilib-loader';\n\nconst loader = LoaderFactory();\n```\n\nOnce you have the loader, you can use it to load single files. Without parameters,\nthe loadFile method defaults to asynchronous mode and returns a Promise. With\nthe sync option in the options parameter, you can specify to load the file\nsynchronously. In this case, the contents of the file will be returned directly\nfrom the method.\n\nExamples:\n\n```\nimport LoaderFactory from 'ilib-loader';\n\nconst loader = LoaderFactory();\n\n// asynchronous usage\nloader.loadFile(\"pathname\").then((content) =\u003e {\n    // use the content here\n});\n\n// synchronous usage\nconst content = loader.loadFile(\"pathname\", { sync: true });\n```\n\nAlternately, you can load an array of files all at once by passing in an\narray of file names:\n\n```\nimport LoaderFactory from 'ilib-loader';\n\nconst loader = LoaderFactory();\n\n// asynchronous usage\nloader.loadFiles([\"path1\", \"path2\", \"path3\"]).then((content) =\u003e {\n    // content is:\n    // [\n    //    \"content of path1\",\n    //    \"content of path2\",\n    //    \"content of path3\"\n    // ]\n});\n\n// synchronous usage:\nconst content = loader.loadFile([\"path1\", \"path2\", \"path3\"], { sync: true });\n// content is:\n// [\n//    \"content of path1\",\n//    \"content of path2\",\n//    \"content of path3\"\n// ]\n```\n\nFiles Not Found\n-----------------\n\nIf the caller gives a file name for a file that does not exist, there is no\nexception thrown. Instead, an undefined value will be returned. For asynchronous\ncalls, the promise will resolve to an undefined value.\n\nExample:\n\n```\nimport LoaderFactory from 'ilib-loader';\n\nconst loader = LoaderFactory();\n\nloader.loadFiles([\"path1\", \"non-existent-file\", \"path3\"]).then((content) =\u003e {\n    // content is:\n    // [\n    //    \"content of path1\",\n    //    undefined,\n    //    \"content of path3\"\n    // ]\n});\n```\n\nAssumptions About the Loaded Files\n-------------------\n\nFiles with a \".js\", \".cjs\", or \".mjs\" extension will be treated as\na Javascript file. It will be loaded as code, and the module will be returned\nto the caller as a module. The path name should be relative to the current\ndirectory of the app, not relative to the module that is calling the\n`loadFiles` method.\n\nFiles with the extension \".mjs\" will be interpretted as ES modules, and as\nsuch they can only be loaded asynchronously. If you attempt to load it\nsynchronously, the `loadFile` method will return undefined for that file.\n\nFiles with the extension \".js\" and \".cjs\" will be interpretted as CommonJS\nfiles and can be loaded synchronously or asynchronously. As such, if you\nput any ESM code into a \".js\" file, it will be a syntax error and `loadFiles`\nwill return undefined for that file in both synchronous and asychronous modes.\n\nFor other file extensions, no assumptions are made about the contents\nof the files other than these:\n\n- the file is a text file\n- the text is encoded in UTF-8\n\nSpecifically, no assumption is made as to the format of the file, making it equally\npossible to load json files, csv files, or yaml files. The contents are returned\nas a string, and it is up to the caller to interpret the format of that string\nwith the appropriate parser.\n\nFull JS Docs\n--------------------\n\nFull API documentation can be found [here](./docs/ilib-loader.md).\n\nLogging\n--------------------\n\nUse the name \"ilib-loader\" to configure a log4js appender in your app to\nsee logging output from this library. If your app does not use log4js, that is\nokay as well. The log4js output will just go to the bitbucket instead.\n\nUsing this Module in Webpack\n--------------------\n\n### Unnecessary Loader Subclasses\n\nIf you are using this module with your Webpacked application, Webpack will read and\nchase down all dependencies and include them in the bundle, including all of the\nsubclasses of Loader intended for other platforms. Unfortunately, since\nthis package is a js-engine dependent module, some of the subclasses of Loader rely on\nmodules and code which are not available in a browser. These subclasses cannot therefore\nbe included in your app's webpack bundle.\n\nThe solution is to declare that these Loader subclasses are external. That is,\nWebpack will assume that the environment that your app is running in will provide\nthese dependencies already so it doesn't need to include them. In our case, we won't\nactually provide those dependencies, because we don't have to -- code that uses those\ndependencies will never run because it is only used on other platforms. The only loader\nsubclass we really need is the one for webpack.\n\nAdd the following to your webpack.config.js file:\n\n```js\nmodule.exports = {\n    \"externals\": {\n        \"./NodeLoader.js\": \"NodeLoader\",\n        \"./QtLoader.js\": \"QtLoader\",\n        \"./RhinoLoader.js\": \"RhinoLoader\",\n        \"./NashornLoader.js\": \"NashornLoader\",\n        \"./RingoLoader.js\": \"RingoLoader\",\n        \"log4js\": \"log4js\"\n    }\n}\n```\n\nThe last external, \"log4js\", should only be added if your app does not use log4js\nalready. If it does, then it will be in your Webpack bundle already, so you don't\nhave to pretend it is external.\n\n### Including Ilib Classes\n\nIn addition to preparing the externals, you should make sure to include all of\nthe ilib modules into the package. Fortunately, all of the ilib modules have names\nthat start with the prefix \"ilib-\" so they are easy to recognize:\n\n```js\n    module: {\n        rules: [\n            {\n                test: /\\.js$/,\n                exclude: /node_modules/,\n                include: /node_modules\\/ilib-/,\n                use: {\n                    loader: 'babel-loader',\n                    options: {\n                        presets: [[\n                            '@babel/preset-env',\n                            {\n                                useBuiltIns: 'usage',\n                                corejs: {\n                                    version: 3,\n                                    proposals: true\n                                }\n                            }\n                        ]],\n                        plugins: [\n                            //\"add-module-exports\",\n                            \"@babel/plugin-transform-regenerator\"\n                        ]\n                    }\n                }\n            }\n        ]\n    }\n```\n\n### Point Webpack to Your Data Files\n\nFinally, the files containing locale data for ilib classes or containing the translations\nof strings extracted from your app should be assembled using [ilib-assemble](https://github.com/iLib-js/ilib-assemble)\ninto individual files per locale.\nThese files should go into a directory inside your app and the name of that directory\nshould go into a resolve alias called \"calling-module\" in your webpack configuration:\n\n```js\n    resolve: {\n        alias: {\n            \"calling-module\": \"\u003cyour directory here\u003e\"\n        }\n    }\n```\n\nThe webpack loader uses this alias to locate the data files so that it can include them into\nthe webpacked bundle. The webpack loader will create a chunk for each\nof the files it finds in this directory. In this way, you are not loading the data for all\nlocales into memory at the same time when the bundle is loaded. It will dynamically load\nonly the locale data needed for the locales that are being used.\n\n## License\n\nCopyright © 2022-2023, JEDLSoft\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n## Release Notes\n\n### v1.3.3\n\n* Converted all unit tests from nodeunit to jest\n* Node 10 is no longer supported\n\n### v1.3.2\n\n* This module is now a hybrid ESM/CommonJS package that actually works.\n  It avoids much of the dual package hazard by explicitly storing the\n  cache of registered loaders in the global scope and having no other\n  package state.\n\n### v1.3.1\n\n* Fixed incorrect documentation\n* removed useless polyfills which were causing code bloat\n\n### v1.3.0\n\n* Now ships both the ES6 modules in the src directory and the commonjs code\n  (transpiled with babel) in the lib directory. Callers can choose which one\n  they would like to use.\n\n### v1.2.0\n\n- added the ability to load JS files instead of just json files.\n    - if the file name extension is \".js\", the node loader will use\n      `require()` in sync mode and `import()` in async mode\n    - the webpack loader will always use `import()` as it only supports\n      async mode\n    - the value returned is a module\n        - this may be an object, which may include a \"default\" property\n          that contains a function to call to get the locale data\n        - for some modules (CommonJS), the module may be a function\n          directly which can be called to get the locale data\n- Fix incorrect call to logger\n\n### v1.1.1\n\n- the npm package for the previous version was built with the wrong babel target on\n  a later version of node that didn't require most polyfills, so many things were not\n  polyfilled properly for older node or older browsers\n\n### v1.1.0\n\n- Add webpack loader subclass\n- Minimum version of node is now v10\n- Added babel configuration to polyfill Promise.allSettled on older versions of node\n  or older browsers\n\n### v1.0.3\n\n- add core-js to the dependencies so that this works properly as a package\n\n### v1.0.2\n\n- use correct package name for the node fs packages for promises so that\n  we don't use the polyfill all the time\n- fix problem with missing variable declaration\n- added some debugging output\n\n### v1.0.1\n\n- use the global scope to store class instances so that all copies\n  of this library use the same class cache\n- update dependencies\n- add more to this README.md\n\n### v1.0.0\n\n- Initial version which only supports loading files on Nodejs. Later\n  updates to this package will introduce support for webpack, Qt, etc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filib-js%2Filib-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-loader/lists"}