fix(documentation): Update description and keywords in package.json

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2024-12-31 - 1.1.4 - fix(documentation)
+Update description and keywords in package.json
+
+- Corrected the package description to reflect the focus on managing, accessing, and updating open data with MongoDB integration.
+- Expanded the keywords in the package metadata to include data integration and processing terms.
+- Improved README.md with more extensive setup, usage, and introduction of the library's functionalities.
+
 ## 2024-12-31 - 1.1.3 - fix(core)
 Added missing license file for project completeness.
 

npmextra.json

@@ -5,7 +5,7 @@
       "githost": "gitlab.com",
       "gitscope": "fin.cx",
       "gitrepo": "opendata",
-      "description": "A TypeScript-based library for accessing and managing open business data, specifically for German companies.",
+      "description": "A TypeScript library for accessing, managing, and updating open business data, focused on German companies and integrating with MongoDB.",
       "npmPackagename": "@fin.cx/opendata",
       "license": "MIT",
       "projectDomain": "fin.cx",
@@ -17,9 +17,13 @@
         "data management",
         "business registry",
         "npm package",
-        "database",
         "MongoDB",
-        "automation"
+        "automation",
+        "data integration",
+        "database",
+        "data processing",
+        "data retrieval",
+        "data update"
       ]
     }
   },

package.json

@@ -2,7 +2,7 @@
   "name": "@fin.cx/opendata",
   "version": "1.1.3",
   "private": false,
-  "description": "A TypeScript-based library for accessing and managing open business data, specifically for German companies.",
+  "description": "A TypeScript library for accessing, managing, and updating open business data, focused on German companies and integrating with MongoDB.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
@@ -63,8 +63,12 @@
     "data management",
     "business registry",
     "npm package",
-    "database",
     "MongoDB",
-    "automation"
+    "automation",
+    "data integration",
+    "database",
+    "data processing",
+    "data retrieval",
+    "data update"
   ]
 }

readme.md

@@ -1,6 +1,6 @@
-```markdown
 # @fin.cx/opendata
-open business data
+
+A TypeScript-based library for accessing and managing open business data, specifically for German companies.
 
 ## Install
 
@@ -20,234 +20,199 @@ yarn add @fin.cx/opendata
 
 ## Usage
 
-The `@fin.cx/opendata` package offers functionalities for handling open business data, with a primary focus on German business data. Let's explore its capabilities through detailed examples.
+The `@fin.cx/opendata` package provides a comprehensive set of functionalities for handling open business data, focusing on German business data. Let's explore the detailed capabilities of this library through extensive examples and instructions.
 
-### Setting Up
+### Setting Up the Environment
 
-#### Importing the Module
+First, make sure you've set up the necessary environment variables for MongoDB. You will need the following environment variables:
+- `MONGODB_URL`: The URL for your MongoDB instance.
+- `MONGODB_NAME`: The name of the database to use.
+- `MONGODB_USER`: A valid username for accessing the database.
+- `MONGODB_PASS`: The password associated with the MongoDB user.
 
-Begin by importing necessary components from the `@fin.cx/opendata` package. You'll also need to set up some environment variables for the MongoDB instance.
+These variables can be configured in a `.env` file or managed through a specific service used for secure environment variables handling.
+
+### Importing and Initializing the Library
+
+To start working with the library, import the necessary classes and initialize the `OpenData` class.
 
 ```typescript
 import { OpenData } from '@fin.cx/opendata';
 
-const startOpenDataInstance = async () => {
+const initializeOpenData = async () => {
   const openData = new OpenData();
   
-  await openData.start(); // Start the open data instance
+  try {
-  console.log('OpenData instance started.');
+    await openData.start();
+    console.log('OpenData instance has started successfully.');
     
-  // your code here
+    // Example usage:
+    await createAndManageBusinessRecords(openData);
 
+  } catch (error) {
+    console.error('Error starting OpenData:', error);
+  } finally {
     await openData.stop();
-  console.log('OpenData instance stopped.');
+    console.log('OpenData instance has stopped.');
+  }
 };
 
-startOpenDataInstance().catch(console.error);
+initializeOpenData();
 ```
 
-### BusinessRecord Usage
+### Managing Business Records
 
-A `BusinessRecord` is the main entity you'll be working with. Here's how you manage business records.
+The `BusinessRecord` class represents a company's data. Let's explore how you can create, retrieve, update, and manage these records.
 
 #### Creating a New BusinessRecord
 
+Creating a new business record involves instantiating the `BusinessRecord` class and setting the relevant properties.
+
 ```typescript
 import { BusinessRecord } from '@fin.cx/opendata';
 
 const createBusinessRecord = async (openData: OpenData) => {
   const businessRecord = new openData.CBusinessRecord();
-  businessRecord.data.name = "Example Company";
+  
-  businessRecord.data.address = "Example Street 1";
+  businessRecord.data = {
-  businessRecord.data.postalCode = "12345";
+    name: "Tech Innovations GmbH",
-  businessRecord.data.city = "Example City";
+    address: "Tech Park 42",
-  businessRecord.data.country = "Germany";
+    postalCode: "80333",
-  businessRecord.data.phone = "+49 123 456789";
+    city: "Munich",
-  businessRecord.data.email = "contact@example.com";
+    country: "Germany",
-  businessRecord.data.website = "https://example.com";
+    phone: "+49 89 123456",
-  businessRecord.data.businessType = "GmbH";
+    email: "info@techinnovations.de",
-  businessRecord.data.registrationNumber = "HRB 123456";
+    website: "https://techinnovations.de",
-  businessRecord.data.registrationCourt = "Munich";
+    businessType: "GmbH",
-  businessRecord.data.legalForm = "GmbH";
+    registrationNumber: "HRB 654321",
-  businessRecord.data.managingDirectors = ["John Doe", "Jane Smith"];
+    registrationCourt: "Munich",
-  businessRecord.data.foundingDate = new Date().toISOString();
+    legalForm: "GmbH",
-  businessRecord.data.capital = "50,000 EUR";
+    managingDirectors: ["Alice Müller", "Bob Schmidt"],
-  businessRecord.data.purpose = "Tech Solutions";
+    foundingDate: new Date("2020-01-01").toISOString(),
-  businessRecord.data.lastUpdate = new Date().toISOString();
+    capital: "100,000 EUR",
+    purpose: "Developing innovative tech solutions",
+    lastUpdate: new Date().toISOString()
+  };
 
   await businessRecord.save();
   console.log('BusinessRecord saved:', businessRecord);
 };
 ```
 
-#### Retrieving BusinessRecord
+#### Retrieving Business Records
 
-Retrieve a business record by querying the database.
+You can retrieve existing business records by querying the database using various data fields.
 
 ```typescript
-import { BusinessRecord } from '@fin.cx/opendata';
+const retrieveBusinessRecords = async (openData: OpenData) => {
+  const records = await openData.db
+    .collection<BusinessRecord>('businessrecords')
+    .find({ city: "Munich" })
+    .toArray();
 
-const findBusinessRecord = async (openData: OpenData) => {
+  console.log('Found Business Records:', records);
-  const businessRecords = await openData.db.collection<BusinessRecord>('businessrecords').find().toArray();
-  console.log('Retrieved Business Records:', businessRecords);
 };
 ```
 
-### Updating Business Data
+#### Updating Existing Records
 
-The `GermanBusinessData` class handles the specifics of updating and maintaining the data.
+To update an existing `BusinessRecord`, you retrieve the record, modify its data, and save it again.
-
-#### Updating German Business Data
 
 ```typescript
-import { OpenData } from '@fin.cx/opendata';
+const updateBusinessRecord = async (openData: OpenData, recordId: string) => {
+  const businessRecord = await openData.CBusinessRecord.getInstance(recordId);
+  if (businessRecord) {
+    businessRecord.data.phone = "+49 89 987654";
+    businessRecord.data.lastUpdate = new Date().toISOString();
 
+    await businessRecord.save();
+    console.log('BusinessRecord updated:', businessRecord);
+  } else {
+    console.log('BusinessRecord not found for id:', recordId);
+  }
+};
+```
+
+#### Deleting a Business Record
+
+You can delete a business record using its unique identifier.
+
+```typescript
+const deleteBusinessRecord = async (openData: OpenData, recordId: string) => {
+  const businessRecord = await openData.CBusinessRecord.getInstance(recordId);
+  if (businessRecord) {
+    await businessRecord.delete();
+    console.log(`BusinessRecord with id ${recordId} deleted successfully.`);
+  } else {
+    console.log('No record found for the provided id:', recordId);
+  }
+};
+```
+
+### Updating German Business Data
+
+The package includes functionalities to keep your business data up-to-date by downloading from official German open data repositories.
+
+```typescript
 const updateGermanBusinessData = async (openData: OpenData) => {
+  try {
     await openData.germanBusinesses.update();
-  console.log('German business data updated.');
+    console.log('German business data has been updated successfully.');
+  } catch (error) {
+    console.error('Error updating German business data:', error);
+  }
 };
-
-startOpenDataInstance()
-  .then((openData) => {
-    // Use the instance
-    return updateGermanBusinessData(openData);
-  })
-  .catch(console.error);
 ```
 
-This function downloads the latest data from the German business data source, processes it, and updates the local database.
+This function fetches the latest open data regarding German companies, processes it, and updates your local database.
 
-### Detailed Class Structures and Methods
+### Detailed Class Insights
 
 #### OpenData Class
 
-The `OpenData` class is the main entry point.
+The `OpenData` class serves as the core of the library, initializing necessary components and controlling data flows:
+
+- **db**: Represents the connection to your MongoDB database.
+- **germanBusinesses**: An instance handling specific operations related to German business data updates.
 
 ```typescript
-import { OpenData } from '@fin.cx/opendata';
-
 class OpenData {
   db: plugins.smartdata.SmartdataDb;
   germanBusinesses: GermanBusinessData;
 
   private serviceQenv = new plugins.qenv.Qenv(paths.packageDir, paths.nogitDir);
 
-  public CBusinessRecord = plugins.smartdata.setDefaultManagerForDoc(this, BusinessRecord);
-
   public async start() {
-    // Initialize smart data DB
+    // Database initialization logic
-    this.db = new plugins.smartdata.SmartdataDb({
-      mongoDbUrl: await this.serviceQenv.getEnvVarOnDemand('MONGODB_URL'),
-      mongoDbName: await this.serviceQenv.getEnvVarOnDemand('MONGODB_NAME'),
-      mongoDbUser: await this.serviceQenv.getEnvVarOnDemand('MONGODB_USER'),
-      mongoDbPass: await this.serviceQenv.getEnvVarOnDemand('MONGODB_PASS'),
-    });
-
-    await this.db.init();
-    this.germanBusinesses = new GermanBusinessData(this);
-    await this.germanBusinesses.start();
   }
 
   public async stop() {
-    // Clean up resources if necessary
+    // Cleanup logic
   }
 }
 ```
 
 #### GermanBusinessData Class
 
-The `GermanBusinessData` class handles the specifics of German business data.
+This class deals specifically with German company data — fetching, processing, and updating local databases consistently with official German data sources.
 
 ```typescript
-import { OpenData } from '@fin.cx/opendata';
-import * as plugins from './plugins';
-import * as paths from './paths';
-
 class GermanBusinessData {
-  public openDataRef: OpenData;
-
-  constructor(openDataRef: OpenData) {
-    this.openDataRef = openDataRef;
-  }
-
   public async start() {
     await this.update();
   }
 
-  public async stop() {
-    // Stop any ongoing processing
-  }
-
   public async update() {
-    const dataUrl = 'https://daten.offeneregister.de/de_companies_ocdata.jsonl.bz2';
+    // Logic for updating business data using import streams and parsing JSON lines.
-    const dataExists = await plugins.smartfile.fs.isDirectory(paths.germanBusinessDataDir);
-
-    if (!dataExists) {
-      await plugins.smartfile.fs.ensureDir(paths.germanBusinessDataDir);
-    }
-    
-    const smartarchive = await plugins.smartarchive.SmartArchive.fromArchiveUrl(dataUrl);
-    const jsonlDataStream = await smartarchive.exportToStreamOfStreamFiles();
-
-    let totalRecordsCounter = 0;
-    let nextRest: string = '';
-
-    jsonlDataStream.pipe(
-      new plugins.smartstream.SmartDuplex({
-        objectMode: true,
-        writeFunction: async (chunkArg: plugins.smartfile.StreamFile, streamToolsArg) => {
-          const readStream = await chunkArg.createReadStream();
-          readStream.pipe(
-            new plugins.smartstream.SmartDuplex({
-              objectMode: true,
-              writeFunction: async (chunkArg: Buffer, streamToolsArg) => {
-                const currentString = nextRest + chunkArg.toString();
-                
-                const lines = currentString.split('\n');
-                nextRest = lines.pop();
-
-                for (const line of lines) {
-                  let entry: any;
-                  try {
-                    entry = JSON.parse(line);
-                  } catch (err) {
-                    console.error('Error parsing line:', err);
-                    continue;
-                  }
-                  
-                  totalRecordsCounter++;
-                  if (totalRecordsCounter % 10000 === 0) {
-                    console.log(`${totalRecordsCounter} total records.`);
-                  }
-                  
-                  const businessRecord = new this.openDataRef.CBusinessRecord();
-                  businessRecord.data.name = entry?.name;
-
-                  await businessRecord.save();
-                }
-              },
-              finalFunction: async (streamToolsArg) => {
-                if (nextRest) {
-                  try {
-                    JSON.parse(nextRest);
-                  } catch (err) {
-                    console.error('Error parsing final chunk:', err);
-                  }
-                }
-              }
-            })
-          );
-        },
-      })
-    );
   }
 }
 ```
 
-### Conclusion
+### Ensuring Data Accuracy and Integrity
 
-This module is designed to make it easier to manage open business data, especially focusing on German business data. The examples above demonstrate the core functionalities, including starting and stopping the service, managing business records, and updating data.
+When working with business data, ensuring integrity and accuracy is crucial. Each record should be checked for validity before being saved or updated, minimizing inconsistencies. Moreover, robust error handling is essential in every step, from data retrieval to database operations, particularly when dealing with external data sources.
 
-As you work with `@fin.cx/opendata`, you’ll discover it offers a robust and flexible approach for working with open business data seamlessly. Happy coding!
+The `@fin.cx/opendata` module provides an extensive toolset for accessing and managing business data, particularly for companies based in Germany. Its functionalities include creating, updating, retrieving, and deleting business records, as well as keeping them current with the latest open data releases. This makes it an invaluable asset for developers aiming to integrate open data seamlessly into their systems, ensuring robust data management capabilities within their applications.
-```
+
+Happy exploring and integrating open data into your projects!
 undefined

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '1.1.3',
+  version: '1.1.4',
-  description: 'A TypeScript-based library for accessing and managing open business data, specifically for German companies.'
+  description: 'A TypeScript library for accessing, managing, and updating open business data, focused on German companies and integrating with MongoDB.'
 }